spree-i18n

Spree I18n + Translations

Two distinct translation surfaces, each with its own mechanism:

You need both for a multilingual store. UI strings are about how the app speaks; data translations are about what merchant content the customer sees.

UI strings — Spree.t and the YAML files

Every Spree gem ships its own English locale file. Spree.t looks up a key scoped under spree.* in the active locale:

Spree.t(:save)                             # => "Save"
Spree.t('i18n.this_file_language')         # => "English (US)"
Spree.t(:paid, scope: 'payment_states')    # => "Paid"
Spree.t(:missing_key, default: 'Fallback') # => "Fallback"

In views / helpers, the shorthand is just Spree.t(...). In ERB templates, you can also use <%= t('.relative_key') %> for lazy lookup based on the controller + action name (standard Rails).

Adding a new UI language

1. Install the translations gem (community-maintained):

   # Gemfile
   gem 'spree_i18n'   # ships translations for 40+ locales
   

   This adds config/locales/<locale>.yml files for every Spree gem in the bundle.

2. Add the locale to your store's supported list:

   # backend/config/initializers/spree.rb
   I18n.available_locales = %i[en es fr de it ja]
   I18n.default_locale = :en
   

3. (Optional) Add the locale to the relevant market's supported_locales so the storefront language switcher offers it. Locales are configured per Market, not on the store:

   store = Spree::Store.default
   store.default_market.update!(supported_locales: ['es', 'fr'])
   

   supported_locales accepts an Array or a comma-separated string; default_locale also lives on the market. When a store has markets (the norm — stores created with a default_country_iso, including seeds and the admin flow, get a default market automatically), market values take precedence: Store#supported_locales_list comes entirely from the markets, and Store#default_locale returns the default market's locale — falling back to the store column only when the market's default_locale is blank. With no markets at all, the store-level columns are used directly.