Internationalization
Overview
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 files. To translate models (provide translations for Products, Taxons, etc) you will need to install also spree_globalize.
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"
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.
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
.
Spree has over 43 locale files and counting. See the GitHub Repository for a complete list.
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
Model Translations
Like mentioned before to translate models you will need to install Spree Globalize extension which uses Globalize library under the hood.
This gem will allow you to translate:
- Products
- Promotions
- Option Types
- Taxonomies
- Taxons
- Properties
- Shipping Methods
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
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
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.
Multi-currency support
To add multiple currency support to your application please install Multi Currency extension.
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
Please submit Pull Requests or issues directly to 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).
Since Spree extensions are equivalent to Rails Engines they can provide localization information automatically (just like a standalone Rails application.)