This guide covers how Spree uses Rails' internationalization features, and how you can leverage and extend these features in your Spree contributions and extensions.
Each Store has their own
default_localeattribute. Alongside that, you can also set
supported_localeswhich will enable multi-language capabilities for that Store.
For locales, we use symbols such as
es-MXetc - full list of supported locales is available in the Spree I18n GitHub repository.
Each Store has their own
default_currencyattribute. Alongside that, you can also set
supported_currencieswhich will enable multi-currency capabilities for that Store.
As of Spree 4.6, resources with user-facing content fields now have built in support for translations. Translation functionality is handled by the Mobility gem. Spree allows you to translate the following resources:
name, description, slug, meta_description, meta_keywords, meta_title
name, description, permalink
name, presentation, filter_param
name, meta_description, meta_keywords, seo_title, facebook, twitter, instagram, customer_support_email, description, address, contact_phone, new_order_notifications_email
Our translatable resources are configured with Mobility’s Table Backend storage strategy. The way this works is that each translatable resource has a corresponding translations table in the database, in which translation values are stored - for example, product translations are stored in
As of 4.6, data for translatable fields exists solely in the the translation tables so that there is a single source of truth. In the database, the translatable fields on the resource itself will always null. Even if there is only data for a single language, the data for those fields will be stored in the corresponding translations table. In the code, the data will still be accessible via attribute accessors like
.descriptionin the code. Read more about how to work with translations by reading Mobility's usage docs.
If you are using Spree version 4.5 or lower and are currently unable to upgrade, you need to install Spree Globalize extension to enable translations. This extension uses Globalize library under the hood.
This gem will allow you to translate:
- Option Types
- Shipping Methods
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:
All translations for Spree are "namespaced" within the
spreekey 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](https://github.com/spree/spree_i18n/tree/master/config/locales) 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-i18nfor their translations to be available within your application. They are made available automatically, because both
This section is only applicable for optional
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,
rails-i18n. Its relative key within those translation files would need to be this:
Spree extensions can contain their own
config/localesdirectory 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).