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"

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

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