Translate theme strings

What’s in this topic

Your custom theme might contain new strings that are not present in the Magento out of the box themes. To ensure that your theme is displayed correctly with any language applied on a store view, you need to make sure that the unique strings of your theme are added to the translation dictionary when the i18n tool is run. Then when a new language package is created and used to translate a store view, all theme strings are translated as well.

This topic describes how to add theme strings in a way that they get collected by the i18n tool and are added to the dictionary.

Contents

• Strings added in .phtml templates
• Strings added in email templates
• Strings added in UI components’ templates
• Strings added in UI components configuration files
• Strings added in .js files

Strings added in .phtml templates

To ensure that your new string is added to the dictionary and translated, use the __('<your_string>') method when outputting a string in a .phtml template.

For example:

<h3><?php echo __('Create Backup') ?></h3>

If your string contains a variable, to add a placeholder for this variable in the dictionary, use syntax similar to the following:

<h3><?php echo sprintf(__('Hello %s'), $yourVariable) ?></h3>

In this example, the ‘Hello %s’ string is added to the dictionary when the i18n tool is run.

Strings added in email templates

If your theme contains custom email templates, their strings can be added to the dictionary as well. To make sure the strings of an email template are added to the dictionary, use the {{trans}} directive.

Custom email templates added using the Admin panel, are not stored in the file system, and their stings are not added to the dictionary.

Strings added in UI components' templates

To ensure that the text you add in .html templates of UI components is added to the dictionary, mark the text using the i18n custom binding. The following code samples illustrate how it should be used for different cases of adding a text:

• when a string is added in the scope of an HTML element:

<span data-bind="i18n: 'Sign In'"></span>

• when a string is added with no binding to an HTML element:

<!-- ko i18n: 'You have no items in your shopping cart.' --><!-- /ko -->

Strings added in UI components configuration files

To ensure that the text you add in UI components configuration .xml files is added to the dictionary, use the translate attribute: set translate=true for the corresponding element. The following code sample is an illustration:

<item name="label" xsi:type="string" translate="true">Delete</item>

In this example, the Delete string is added to the dictionary when the i18n tool is run.

Strings added in .js files

To ensure that the text you add in a .js file is collected by the i18n tool and added to the dictionary, take the following steps:

1. Link the mage/translate library:

   define (['jquery', 'mage/translate'], function ($) {...});

2. Use the $.mage.__('') function when adding a string:

   $.mage.__('<string>');

   If your string contains a variable, to add a placeholder for this variable to the string stored in the dictionary, use the syntax similar to the following:

   $.mage.__('Hello %1').replace('%1', yourVariable);

   In this example, the 'Hello %1' string is added to the dictionary when the i18n tool is run.