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 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.
You will need to install the spree_i18n gem if you want to use any of the community supplied translations of Spree.
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"
All translations for Spree are “namespaced” within the
spree key so that they
don’t conflict with translations from other parts of the parent application.
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
Spree has over 43 locale files and counting. See the GitHub Repository for a complete list.
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
You don’t need to copy any files from
rails-i18n for their
translations to be available within your application. They are made available
automatically, because both
rails-i18n are railties.
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
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
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/application.rb. This setting is ignored
unless the relevant translation file are within
Setting the Default Currency
This functionality was new in Spree 1.2. Please refer to the appropriate guide if you are using an older version.
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.
Localizing Seed Data
Spree use Carmen to seed the Country and State data. You can localize the seed data by adding Carmen configuration to your
seeds.rb. See example below:
# add Carmen counfiguration with the following 2 lines require 'carmen' Carmen.i18n_backend.locale = :ja Spree::Core::Engine.load_seed if defined?(Spree::Core) Spree::Auth::Engine.load_seed if defined?(Spree::Auth)
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.
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).
Since Spree extensions are equivalent to Rails Engines they can provide localization information automatically (just like a standalone Rails application.)