Translations overview

Overview of translations

The Magento application enables you to localize your store for multiple regions and markets. We improved the localization and customization of Magento instances by making translation dictionaries easier to update and by maintaining a reduced amount of code coupling and duplication.

Terms used

A translation dictionary is a comma-separated value (.csv) file with at least two columns: the original phrase in the en_US locale and a translation of that phrase in an another locale. Sample translation from English (en_US) to German (de_DE):

"Add to Cart","Zum Warenkorb hinzufügen"
"Add to Compare","Hinzufügen um zu vergleichen"
"Add to Wishlist","Zum Wunschzettel hinzufügen"
"Additional Product Info","Zusätzliche Angaben zum Produkt"
"Address","Adresse"
"Address %1 of %2","Adresse %1 von %2"

A language package is basically a collection of translation dictionaries for a particular language together with meta-information. You can also distribute language packages to other merchants if you wish. More information about language packages.

Benefits

Benefits include:

• Two types of language packages:

  • Module and theme packages. Included in the i18n directory of a module or theme, the Magento application auto-discovers these packages.

  • An entire dictionary in one directory.

    This is intended to be used and distributed as a standalone component (similar to modules and themes).

• You can use the ready-to-use language packages prepared by other users or you can create your own.
• You can create localizations based on existing, or parent, translations using language inheritance. Inheritance means (among other things) that if you missed or omitted localizing some phrases or terms, parent translations are used.
• You can customize your translations even further by creating more than one version of a translation for the same language.

Depending on your needs, you can use the existing language packages or translate Magento by yourself.

Changes in Magento 2

Changes made:

• The language package (i18n directory) can now be moved and saved to any directory of your extension.
• The phrases for translations are enabled in the Phrase class.

Programming notes

• It is recommended, but not enforced, that you do not place variables inside __() functions or new Phrase() calls. The scanner that collects the phrases from the code cannot interpret and collect the value of the variable when it is in these locations. Instead, you should place the full text in the __() function or new Phrase() call. If you need to specify a variable in these cases, ensure that it is translated correctly wherever it is defined as a string literal.

More information

See one of the following sections for more information:

• Why you might need to add a dictionary for a theme
• Manually translate words and phrases
• Translation dictionaries
• Language packages

Why you might need to add a dictionary for a theme

You might need to add a dictionary for the default language (en_US) in the following cases:

• if you want to replace certain strings from the parent theme. For example, use “Compare” instead of “Add to Compare”.
• if you want your theme to be ready for localization.

For practical illustration of creating a dictionary for a theme for both cases, see the Create a translation dictionary for a theme topic.

Manually translate words and phrases

Translating the names, titles and phrases used in Magento involves the following steps:

1. Generate a dictionary of your instance using the translation dictionary tool.
2. Translate the terms.
3. If desired, package your translations in a language package.

Anyone can submit translations on the storefront using the Text Editor. Changes made in the Text Editor are not recorded in an instance’s dictionary; instead, they are stored in the database. In the storefront, an inline translation of a phrase overwrites the translation stated in a dictionary. However, inline translations are theme-specific and do not apply if another theme is assigned.

Translation dictionaries

Magento translates words and phrases when all of the following conditions are met:

• The Magento code base has the necessary translation dictionaries for a language
• This language is configured by the store administrator to be used in specified scope (that is, storefront)

The Magento application automatically assembles translation dictionaries located in modules’ i18n directory into a dictionary per language. For example, Brazilian Portuguese (pt_BR) translation dictionaries might be located in module and theme directories similar to the following:

<Magento_Checkout_module_dir>/i18n/pt_BR.csv
<Magento_Checkout_module_dir>/<theme>/i18n/pt_BR.csv

Assembling the preceding pt_BR.csv files across all modules and the current theme results in a Portuguese translation of the entire application area (storefront or the Admin).

The dictionary generator tool

More information about the dictionary generator tool.

Language packages

Magento enables you to create the following types of language packages:

• A set of .csv files for modules and themes. These packages files are intended to be deployed in modules. For example:

  __/app
   |__/code
   | |__/Magento
   |   |__/Catalog
   |   | |__/i18n
   |   |   |-- pt_BR.csv
   |   |__/Checkout
   |   | |__/i18n
   |   |   |-- pt_BR.csv
   |   |__/Customer
   |     |__/i18n
   |       |-- pt_BR.csv
   |__/design
     |__/frontend
       |__/<Vendor>
         |__/<theme>
           |__/i18n
             |-- pt_BR.csv
  

• Language packages that contain a entire dictionary in one directory.

  You can distribute this language package as a standalone component (similar to modules and themes). Interestingly, it violates Magento’s modularity principles on purpose; that is, so that a system integrator can translate variations provided by extensions.

In addition to the .csv file that contains the language dictionary, the language package contains meta-information:

• composer.json that contains any dependencies for the language package and a mapping to its defined locale

  Sample composer.json

• language.xml, in which you declare a language package.

  Sample language.xml

Next step

To create translation dictionaries and language packages, see Translation dictionaries and packages.