Magento offers a powerful system to translate strings used in templates, e-mails, and other components. There are several locations where you can place translations; they are loaded in the following order:
- Magento database (inline translations).
- Theme translations located in
<theme>/i18n/<locale>.csv. - Parent theme translations (until no further parent is specified).
- Translation packages located in
app/i18n/<locale>. - Module translations located in
<module>/i18n/.
In this recipe, we will change a translation for the en_US language; if you want, you can add other languages to your theme also.
This recipe will use the theme created in the Creating a new theme recipe of this chapter, but you can apply it to your own custom theme also.
- Create your local translations file:
app/design/frontend/Genmato/default/i18n/en_US.csv"Add to Cart","Buy"
- After uploading the file to your Magento installation, refresh the cache:
bin/magento cache:clean
- If you now reload the page, the new translation should be visible:
In Magento, all translatable strings are used in the following ways:
- Template files (
.phtml):<?php echo __('[text to translate]') ?> - UI component templates:
<span data-bind="i18n: '[text to translate]'"></span>
- XML files:
<item name="label" xsi:type="string" translate="true">[text to translate]</item>
- JavaScript files: (To use translations in JavaScript files, you need to include the
mage/translatemodule through RequireJS.)define (['jquery', 'mage/translate'], function ($) {...}); - Next, you can use the translation in your script:
$.mage.__('<text to translate>');
The translation files in the theme are stored as a comma-separated file, where you can specify the original word/phrase and translation in the following format:
"[original string]","[translation]"
It is important that you place only a single translation on a line. Additionally, the original string must match the case; otherwise, no translation can be done.
Some translations use dynamic values in the translation; these translations are created with %x (where x is a number) in the string:
"Quantity was recalculated from %1 to %2","Quantity was recalculated from %1 to %2"
In Magento 2, there is now an easy option to generate a translation file for your theme or module. To generate the custom translations file for your theme, you can use the following command:
bin/magento i18n:collect-phrases –output=" /app/design/frontend/Genmato/default/i18n/en_US.csv" app/design/frontend/Genmato/default
This command will output only translatable strings that are used in your template. It will not include files from your parent theme(s) or module template files. The generated file can now be edited and, if necessary, you can add extra lines with translations for phrases that are not used in your own theme but you still want to translate.