Internationalization - Developer Guide | Spree Commerce

This guide covers how Spree uses Rails’ internationalization features, and how you can leverage and extend these features in your Spree contributions and extensions.

How Spree i18n works

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.

The spree_i18n project

Spree now stores all of the translation information in a separate GitHub project known as spree_i18n. This is a stand alone project with a large number of volunteer committers who maintain the locale files. This is basically the same approach followed by the Rails project which keeps their localizations in rails-i18n.

The project is actually a Spree extension. This extension contains translations and uses the globalize3 gem to provide translations for model records.

Translation Files

Each language is stored in a YAML file located in config/locales. Each YAML file contains one top level key which is the language code for the translations contained within that file. The following is a snippet showing the basic layout of a locale file:

pt-BR:
  spree:
    say_no: "Não"
    say_yes: "Sim"

Localization Files

Spree maintains its localization information in a YAML file using a naming convention similar to that of the Rails project. Each of the localization filenames contains a prefix representing the language code of the locale. For example, the Russian translation is contained in config/locales/ru.yml.

Required Files

Each locale that you wish to support will require both a Rails and Spree translation. The required Spree translation files are available automatically when you install the spree_i18n gem.

You don’t need to copy any files from spree_i18n or rails-i18n for their translations to be available within your application. They are made available automatically, because both spree_i18n and rails-i18n are railties.

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:

<%= Spree.t(:price) %>

The Spree.t() helper method looks up the currently configured locale and retrieves the translated value from the relevant locale YAML file. Assuming a default locale, this translation would be fetched from the en translations collated from the application, spree_i18n and rails-i18n. Its relative key within those translation files would need to be this:

en:
  spree:
    price: Price

The Default Locale

Since Spree is basically a Rails application it has the same default locale as any Rails application. The default locale is en which use the English language. We can verify this in the rails console

>> I18n.locale
=> :en

You can also see in the console how the default locale values are translated into English

>> Spree.t(:action)
=> Action

Deploying the Translations

The spree_i18n gem is configured in the same manner as any Rubygem in a Rails application. Simply add it to the Gemfile. using the git url.

gem 'spree_i18n', :github => 'spree/spree_i18n'

Setting the Default Locale

The default locale for Rails, and therefore Spree, is en. This can be changed by setting config.i18n.default_locale in config/application.rb. This setting is ignored unless the relevant translation file are within #{Rails.root}/config/locales or the spree_i18n gem.

Setting the Default Currency

In earlier versions of Spree, we used number_to_currency to display prices for products. This caused a problem when somebody selected a different I18n locale, as the prices would be displayed in their currency: 20 Japanese Yen, rather than 20 American Dollars, for instance.

To fix this problem, we’re now parsing the prices through the Money gem which will display prices consistently across all I18n locales. To now change the currency for your site, go to Admin, then Configuration, then General Settings. Changing the currency will only change the currency symbol across all prices of your store.

There are three configuration options for currency:

• Spree::Config[:currency]: 3-letter currency code representing the current currency.
• Spree::Config[:currency_symbol_position]: Whether to include the symbol before or after the monetary amount.
• Spree::Config[:display_currency]: Whether or not to display the currency with prices.

Creating and Modifying Locales

While we have used LocaleApp in the past to manage the translations for the spree_i18n project, Localeapp does not have support for different branches within the same project. As such, please submit Pull Requests or issues directly to https://github.com/spree/spree_i18n for missing translations.

Localizing 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 Spree.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).