layout	group	subgroup	title	menu_title	menu_node	menu_order	version	github_link	redirect_from
default	config-guide	04_CLI	Translation dictionaries and language packages	Translation dictionaries and language packages		260	2.0	config-guide/cli/config-cli-subcommands-i18n.md	/guides/v1.0/config-guide/cli/config-cli-subcommands-i18n.html

Overview of translations

Magento translations enable you to customize and 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 maintain and reduced amount of code coupling and duplication.

This topic discusses how to generate:

Translation dictionaries, which are a convenient way to translate some words and phrases, such as those for a custom {% glossarytooltip c1e4242b-1f1a-44c3-9d72-1d5b1435e142 %}module{% endglossarytooltip %} or {% glossarytooltip d2093e4a-2b71-48a3-99b7-b32af7158019 %}theme{% endglossarytooltip %}.
Language packages, which enable you to translate any or all words and phrases in the Magento application.

For more information, see Translation.

First steps

{% include install/first-steps-cli.html %} In addition to the command arguments discussed here, see Common arguments.

Generate a translation dictionary

You can generate a translation dictionary to use by itself (for example, to translate words and phrases in a custom module) or for use by a {% glossarytooltip 9c4c7b9b-43f0-4454-8e8c-fb62ad40c35f %}language package{% endglossarytooltip %}. See one of the following sections:

About translation dictionaries
Work with translation dictionaries

Work with translation dictionaries

To translate words and phrases, you must:

Run the translation collection command to extract translatable words and phrases from enabled components.
Translate the words and phrases.

After that,

You can package the translation dictionaries into a language package and provide the package to the Magento store administrator.
In the Magento Admin, the store administrator configures the translations.

Command options:

magento i18n:collect-phrases [-o|--output="<csv file path and name>"] [-m|--magento] <path to directory to translate>

The following table discusses the meanings of this command's parameters and values.

<tr>
	<td><p>&lt;path to directory to translate></p></td>
	<td><p>Path to a directory that has translatable code; in other words, PHP, PHTML, or XML files that have phrases to translate.</p>
	<p>The tool starts searching at the path you enter and searches all files and subdirectories it contains. </p>
<p>Do not use this parameter if you use <code>-m|--magento</code>.</p></td>
	
	<td><p>Yes (dictionaries), no (packages).</p></td>
</tr>
<tr>
	<td><p>-m|--magento</p></td>
	<td><p><em>Required to create a language package from this translation dictionary</em>. If used, searches the directories that contain <code>bin/magento</code>. This option adds themes or modules to each line in the dictionary. </p>
		<p>A sample follows:</p>
		<p><pre>"No Items Found","No Items Found",module,Magento_Wishlist</pre></p></td>
		<td><p>No</p></td>

Parameter

Value

Required?

-o|--output="<path>"

Specifies the absolute file system path and file name of the translation dictionary .csv file to create. The value you enter is case-sensitive. The name of the .csv vile must exactly match the locale name, including the characters' case.

If you omit this parameter, the output is directed to stdout.

No

To create a language pack from a translation dictionary, you must use the -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.
While translating, pay attention to placeholders like %1, %2 and so on.

They are used by the Magento application to insert context values; they are not used for translations. For example:
```
Product '%1' has been added to shopping cart.
->
Product 'Multimeter-2000' has been added to shopping cart.
```
The resulting phrase must contain at least one of each placeholder. For example, suppose 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, or %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 Magento application using a language package. (You can translate a particular component—like a module or a theme—using a translation dictionary.) More information 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:

magento i18n:pack [-m|--mode={merge|replace}] [-d|--allow-duplicates] <source> <locale>

The following table discusses the meanings of this command's parameters and values.

<tr>
	<td><p>&lt;source></p></td>
	<td><p>Absolute file system path and file name of a .csv file that contains the combined translation dictionary and meta-information necessary for breakdown into a language package.</p>
	<p>Use <a href="#config-cli-subcommands-xlate-dict-dict">magento i18n:collect-phrases</a> to create the .csv file then create the language package as discussed in <a href="#m2devgde-xlate-files">Create directories and files</a>. </p></td>
	<td><p>Yes</p></td>
</tr>
<tr>
	<td><p>&lt;locale></p></td>
	<td><p><a href="http://www.iso.org/iso/home/standards/language_codes.htm" target="_blank">ISO 639-1</a> (language) and <a href="http://www.iso.org/iso/country_codes.htm" target="_blank">ISO 3166</a> (country) identifier of language used as file name for all resulting .csv files. Examples: <code>de_DE</code>, <code>pt_PT</code>, <code>pt_BR</code>. </p>
	</td>
	<td>
		<p>Yes</p>
	</td>
</tr>
<tr>
	<td><p>-m|--mode</p></td>
	<td><p>If a target file already exists, specifies whether to replace the existing language package or merge with the new language pack. Merging overrides any phrases that existed and adds new ones. </p>
		<p>Values: <code>merge</code> or <code>replace</code> (the default).</p>
	</td>
	<td>
		<p>No</p>
	</td>
</tr>
<tr>
	<td><p>-d|--allow-duplicates</p></td>
	<td><p>Include this option to allow duplicates in the language pack. Otherwise, the command fails with an error if it encounters the same phrase is translated in different ways in different lines.</p>
		
	</td>
	<td>
		<p>No</p>
	</td>
</tr>
</tbody>

Parameter	Value	Required?

Create directories and files

A language package is a directory under `app/i18n/` in the Magento file system with the following contents:

Required license files
composer.json
registration.php that registers the language package
language.xml meta-information file

The entire path must be all lowercase.

For an example, see the de_de language package.

To create these files:

Create a directory under app/i18n.

For example, Magento language packages are located in app/i18n/magento
Add any license files you require.
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 new translation based on an existing one (the existing translation is referred to as the parent). The child translations override the parent. However, if the child translation fails to upload or display, the parent is used instead. If some child translation lacks a phrase or a word, this phrase or word is taken from the parent {% glossarytooltip 05099dbb-d491-4e33-a065-16035cb2d4d9 %}locale{% endglossarytooltip %}. Examples of language package inheritance.

To declare a package, specify the following information:

{% highlight xml %}

en_GB magento en_gb 100 {% endhighlight %}

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 store
<use>: 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 a language package descends from two other packages, and that those packages also have parent and "grandparent" packages.

If a language package descends from two packages, its language.xml might look like the following:

{% highlight xml %} en_GB magento language_pack <sort_order>100</sort_order> {% endhighlight %}

In the preceding example:

language_package_one descends from en_au_package and en_au_package descends from en_ie_package
language_package_two descends from en_ca_package and en_ca_package descends from en_us_package

If the Magento 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 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
Example: Create a language package

Example: Create a translation dictionary for a module or theme

To add a German translation to module or theme you want to distribute to other merchants:

Collect phrases from your module:

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

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 preceding example, generate a .csv file, but instead of specifying a module or theme directory, specify the entire Magento application root directory. The resulting .csv contains any phrases that the command could find in the code.

Collect phrases from your module:
```
magento i18n:collect-phrases -o "/var/www/html/magento2/xx_YY.csv" -m
```
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.

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:

{% highlight 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" ] } } {% endhighlight %}

Sample registration.php:

{% highlight php startinline=true %} /**

See COPYING.txt for license details. */ \Magento\Framework\Component\ComponentRegistrar::register( \Magento\Framework\Component\ComponentRegistrar::LANGUAGE, 'magento_xx_yy', DIR ); {% endhighlight %}

Sample language.xml:

{% highlight XML %}

xx_YY examplecorp xx_yy {% endhighlight %}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

config-cli-subcommands-i18n.md

config-cli-subcommands-i18n.md

Overview of translations

First steps

Generate a translation dictionary

Work with translation dictionaries

Translation guidelines

Create a language package

Run the language package command

Create directories and files

Language package language.xml

Example of language inheritance

Configure multiple packages for a language

Examples of using translation commands

Example: Create a translation dictionary for a module or theme

Example: Create a language package

Related topics

Files

config-cli-subcommands-i18n.md

Latest commit

History

config-cli-subcommands-i18n.md

File metadata and controls

Overview of translations

First steps

Generate a translation dictionary

Work with translation dictionaries

Translation guidelines

Create a language package

Run the language package command

Create directories and files

Language package language.xml

Example of language inheritance

Configure multiple packages for a language

Examples of using translation commands

Example: Create a translation dictionary for a module or theme

Example: Create a language package

Related topics