Internationalization (i18n)

1 How Spree is internationalized

Spree uses the standard Rails approach to internationalization so we suggest take some time to review the official Rails i18n guide and the rails-i18n.org wiki to help you get started.

1.1 Locating Translations

Each language is stored in one or more yaml files located in config/locales. Each yaml file contains one top level key which is the language code for the translations contained within that file:

en-US: 
  abbreviation: Abbreviation
  access_denied: "Access Denied"
  account: Account
  account_updated: "Account updated!"

Within Spree, each language is maintained in two separate files:

1.1.1 Spree Specific Translations

These files are normally named after the language code, ie: en-US.yaml or de.yaml and contain translations specific to Spree.

1.1.2 Rails Generic Translations

These are usually named with the language code followed by _rails, ie: en-US_rails.yaml or de_rails.yaml and these contain generic Rails internationalization options like currency, dates / times, ActiveRecord validation error messages, etc.

These translations are kindly maintained by Sven Fuchs in his GitHub project rails-i18n .

1.2 Translating Views

When reviewing the source of any view in Spree you’ll notice that all text is rendered by passing a string to a helper method similar to:

<%= t('price') %>

The t() helper method looks up the currently configured locale and retrieves the translated value from the relevant locale yaml file.

>> I18n.locale = :"en-US"
=> :"en-US"
>> I18n.t('price')
=> "Price"
>> I18n.locale = :de
=> :de
>> I18n.t('price')
=> "Preis"

1.3 Setting the Default Locale

The default locale for Spree is en-US. This can be changed by editing the :default_locale setting in the AppConfiguration model. In the future we hope to add a localization settings page that will allow you to set the default locale from the admin screen [#35].

2 Adding translations

Spree has two rake tasks that help ease the pain of adding translations:

2.1 Adding a new string to all translations

If you’re working on a patch for Spree it’s vital that you ensure any interface text is present in all translation yaml files and that you use the helper methods to display the relevant translation on all views (or helper methods). to add a new string to all translations you must first add it to the default en-US.yaml file, they run the following rake task to copy it out into the rest of the translation files.

$ rake spree:i18n:sync

This task simply ensures that you’re new string is included in all translations (with the US English value as the default value), and it also alphabetizes all strings in the YAML files!

2.2 Adding a new language

When adding a new language all you need to do is copy the en-US.yml file and rename it to whatever language code you require, you must also change the top level element of this new file to the same language code.

You can do this automatically by running the following rake task (where ja is the new language you want to add):

$ rake spree:i18n:new LOCALE=ja

This rake task will also remind you to download the relevant rails translation file from rails-i18n , which in this example should be saved as ja_rails.yaml.

3 Internationalizing Extensions

Spree extensions can contain their own config/locales directory where developers can include yaml files for each language they wish to support.

We strongly urge all extension developers to ensure all customer facing text is rendered via the t() helper method even if they only include a single default language locale file (as other users can simply include the required yaml file and translations in their site extension).

4 Disabling Internationalization

If you don’t want to allow users to change the language / locale you can disable locale switching by changing the :allow_locale_switching setting to false in the AppConfiguration model.

Guides