Localization
Commerce translations enable you to customize and localize your store for multiple regions and markets by generating:
- Translation dictionaries, which are a convenient way to customize or translate some words and phrases, such as those for a custom module or theme.
- Language packages that enable you to translate any or all words and phrases in the Commerce application.
Generate a translation dictionary
You can generate a translation dictionary to customize existing strings, translate words and phrases in a custom module, localize a theme, or create language packages.
To begin translating, use a command to generate a dictionary CSV file with a collected list of all existing phrases and words.
To generate the dictionary and begin translation:
-
Extract translatable words and phrases from enabled components using the translation collection command. Content extracts into a CSV file.
-
Translate the existing words and phrases. You can add additional custom terms as needed.
You have options for using the translated dictionary:
-
You can package the translation dictionaries into a language package and provide the package to the Commerce store administrator.
-
In the Admin, the store administrator configures the translations.
Command options:
bin/magento i18n:collect-phrases [-o|--output="<csv file path and name>"] [-m|--magento] <path to directory to translate>
The following table explains parameters and values:
<path to directory to translate>
The tool starts searching at the path that you enter and searches all files and subdirectories it contains.
Do not use this parameter if you use
-m --magento
.-m --magento
A sample follows:
“No Items Found”,“No Items Found”,module,Magento_Wishlist
-o --output="<path>"
If you omit this parameter, the output is directed to stdout.
-m|--magento
option.Translation guidelines
Use the following guidelines when translating words and phrases:
- Change the contents of the second column only. Translate the phrases from English (
US
) to the desired language. - When creating dictionaries for locales, use the default Commerce strings.
- While translating, pay attention to placeholders:
%1
,%2
Commerce uses the placeholders to insert context values; they are not used for translations. For example:
Product '%1' has been added to shopping cart.
Populates with a value:
Product 'Multimeter-2000' has been added to shopping cart.
The resulting phrase must contain at least one of each placeholder. For example, suppose that there are placeholders from %1
to %3
in the original phrase. The translation can have as many of these placeholders in any order, but there must be at least one occurrence of %1
, %2
, and %3
. The translation cannot contain placeholder values not present in the original value (for example, %4
, %5
, and so on).
An example of translating a phrase:
"Buy %1 for %2 (%3 incl. tax) each","Compre %1 por %2 (%3 incl. imposto) cada"
Create a language package
As opposed to a translation dictionary, you can translate any or all words and phrases in the Commerce application using a language package. You can translate a particular component—like a module or a theme—using a translation dictionary. Learn more about language packages.
This section discusses how to create a language package, which writes CSV files to modules and themes. To create a language package, you must perform the tasks discussed in the following sections:
- Collect and translate words and phrases. (The
--magento
parameter is required.) - Run the language package command.
- Create directories and files.
- (Optional.) Configure multiple packages for a language.
Run the language package command
Command usage:
bin/magento i18n:pack [-m|--mode={merge|replace}] [-d|--allow-duplicates] <source> <locale>
The following table explains the parameters and values for the language package command:
<source>
Use
bin/magento i18n:collect-phrases
to create the CSV file then create the language package as discussed in Create directories and files.<locale>
de_DE
, pt_PT
, pt_BR
.-m --mode
Values: merge or replace (default).
-d --allow-duplicates
Create directories and files
Language packages are located in a directory under app/i18n/<VendorName>
in the Commerce file system with the following contents:
- Required license files
composer.json
registration.php
that registers the language packagelanguage.xml
meta-information file
de_de
][].To create these files:
-
Create a directory under
app/i18n
.For example, Commerce language packages are located in
app/i18n/magento
-
Add required license files.
-
Add
composer.json
that specifies dependencies for your language package. -
Register the language package with
registration.php
-
Add
language.xml
meta-information file as discussed in the next section.
Language package language.xml
When declaring a language package in the language.xml
configuration file, you must specify the sequence of the language inheritance for this package.
Language inheritance enables you to create a translation called a child based on an existing translation called a parent. The child translations override the parent. However, if the child translation fails to upload or display or is missing a phrase or word, Commerce uses the parent locale. Examples of language package inheritance.
To declare a package, specify the following information:
<?xml version="1.0"?>
<language xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/Language/package.xsd">
<code>en_GB</code>
<vendor>magento</vendor>
<package>en_gb</package>
<sort_order>100</sort_order>
<use vendor="oxford-university" package="en_us"/>
</language>
Where:
code
—Language package locale (required)vendor
—Module’s vendor name (required)package
—Language package name (required)sort_order
—Priority of uploading a package when there are several language packages available for a storeuse
—Parent language package locale from which to inherit dictionaries
If necessary, you can specify several parent packages. The parent packages are applied on a first listed, first used basis.
Example of language inheritance
Suppose that a language package inherits from two other packages, and that those packages also have parent and “grandparent” packages.
If a language package inherits from two packages, its language.xml
might look like the following:
<language xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/Language/package.xsd">
<code>en_GB</code>
<vendor>magento</vendor>
<package>language_pack</package>
<sort_order>100</sort_order>
<use vendor="parent-package-one" package="language_package_one"/>
<use vendor= "parent-package-two" package="language_package_two"/>
</language>
In the preceding example:
language_package_one
inherits fromen_au_package
anden_au_package
inherits fromen_ie_package
language_package_two
inherits fromen_ca_package
anden_ca_package
inherits fromen_us_package
If the Commerce application cannot find word or phrase in the en_GB
package, it looks in other packages in following sequence:
parent-package-one/language_package_one
<vendorname>/en_au_package
<vendorname>/en_ie_package
parent-package-two/language_package_two
<vendorname>/en_ca_package
<vendorname>/en_us_package
Specifying all inheritances between the language packages might result in creating circular inheritance chains. Use Magento\Test\Integrity\App\Language\CircularDependencyTest test to locate and fix such chains.
Configure multiple packages for a language
To help you to make your store more flexible, you can upload several language packages for the same language in your store. Thus, you can use different custom packages for different parts of your store because the system compiles a single package from all packages that are available for a language.
To enable an additional package for an existing language, name the new package any name except for an existing language code name (to avoid confusion). Specify configurations of a package in the language package’s language.xml
meta-information file as discussed in the next section.
Examples of using translation commands
The following sections provide end-to-end examples of using the commands discussed in this topic to create translation dictionaries and translation packages:
Example: Create a translation dictionary for a module or theme
To add a German translation to a module or theme that you want to distribute to other merchants:
-
Collect phrases from your module:
code language-bash bin/magento i18n:collect-phrases -o "/var/www/html/magento2/app/code/ExampleCorp/SampleModule/i18n/xx_YY.csv" /var/www/html/magento2/app/code/ExampleCorp/SampleModule
note info INFO The CSV file name must exactly match the locale, including the characters’ case. -
Translate the words and phrases using these guidelines.
-
If necessary, copy
xx_YY.csv
to/var/www/html/magento2/app/code/ExampleCorp/SampleModule/i18n
or to the module’s theme directory (depending on whether the translation dictionary is for a module or a theme).
Example: Create a language package
Similar to the preceding example, generate a CSV file, but instead of specifying a module or theme directory, specify the entire Commerce application root directory. The resulting CSV contains any phrases that the command could find in the code.
-
Collect phrases from your module:
code language-bash bin/magento i18n:collect-phrases -o "/var/www/html/magento2/xx_YY.csv" -m
note info INFO The CSV file name must exactly match the locale, including the characters’ case. -
Translate the words and phrases using these guidelines.
-
Create the language package.
code language-bash bin/magento i18n:pack /var/www/html/magento2/xx_YY.csv -d xx_YY
-
Create a directory for the language package.
For example,
/var/www/html/magento2/app/i18n/ExampleCorp/xx_yy
-
In that directory, add all of the following:
- A license, if required
composer.json
(sample following)registration.php
(sample following)language.xml
(sample following)
Sample
composer.json
:code language-json { "name": "examplecorp/language-xx_yy", "description": "Sample language", "version": "100.0.2", "license": [ "OSL-3.0", "AFL-3.0" ], "require": { "magento/framework": "100.0.*" }, "type": "magento2-language", "autoload": { "files": [ "registration.php" ] } }
Sample
registration.php
:code language-php <?php /** * Copyright © Magento, Inc. All rights reserved. * See COPYING.txt for license details. */ use Magento\Framework\Component\ComponentRegistrar; ComponentRegistrar::register( ComponentRegistrar::LANGUAGE, 'magento_xx_yy', __DIR__ );
Sample
language.xml
:code language-xml <?xml version="1.0"?> /** * Copyright © Magento, Inc. All rights reserved. * See COPYING.txt for license details. */ <language xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/Language/package.xsd"> <code>xx_YY</code> <vendor>examplecorp</vendor> <package>xx_yy</package> </language>