This guide covers how Spree uses Rails’ internationalization features, and how you can leverage and extend these features in your Spree contributions and extensions.
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.
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 files. To translate models (provide translations for Products, Taxons, etc) you will need to install also Spree Globalize.
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
This gem will allow you to translate:
- Option Types
- Shipping Methods
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
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
We’re parsing the prices through the Money gem which will display prices consistently across all I18n locales. To 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 configuration options for currency:
Spree::Config[:currency]: 3-letter currency code representing the current currency.
This options should be set in
config/initializers/spree.rb file in your application.
To add multiple currency support to your application please install Multi Currency extension.
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)
Please submit Pull Requests or issues directly to 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.)