Magento allows you to translate all phrases, labels, buttons, products and other pages easily. But regardless of the content you're translating, it all starts with the Magento translation dictionaries.
What is a Magento Translation Dictionary?
Translation dictionary is a CSV file with all the words and phrases your Magento store uses. It is used when customising existing website text, translating words or phrases in a custom module, localising a theme, or creating Magento language packs.
Magento Translation Dictionary vs Language Pack
Magento language packs and translation dictionaries are often used interchangeably. Although they are quite similar, their scope and purpose differ.
| Feature | Dictionary | Language pack |
|---|---|---|
| Scope | Translates text within a single module or theme | Translates the entire Magento application |
| Purpose | Translating specific components or edit existing translations | Translating backend and frontend completely to create a multi-language store |
| Structure | Single .csv file with the original text and it's translation. | A package with .csv files for multiple translation dictionaries. |
How to Create a Translation Dictionary?
Creating a translation dictionary in Magento is the first step in creating language packs and translating basic website content.
1. Collect words and phrases from your store. For this, run the following command:
bin/magento i18n:collect-phrases -o “/app/i18n/vendor/en_US.csv” -m
which looks like this, if you want to adjust it to your case:
bin/magento i18n:collect-phrases [-o|--output="<csv file path and name>"] [-m|--magento] <path to directory to translate>
| Element | Description |
|---|---|
| <path to directory> | The folder where Magento should look for phrases in PHP, PHTML, or XML files. Searches all subdirectories too. Not needed if using -m. |
| -o or --output="<path>" | Specifies the location and name of the CSV file to create. Must match locale name exactly. If omitted, output goes to the console. |
| -m or --magento | Tells Magento to generate a language package from this dictionary. Includes modules and themes. |
This command scans your Magento code (PHP, PHTML, XML files) and extracts all the phrases into a CSV file. Here, you can specify particular directories to include all Magento modules and themes.
Important: this command will only find text wrapped in the translation function. So, if you can't find or translate some texts within your store (either from a custom theme or extension), it means that you first need to wrap a text in the translation function.
2. Open the CSV file in Excel, Google Sheets, or any other editor.
3. Translate the phrases and enter the translation in the second column.
Example of the Magento translaiton dictionary with the German (de_DE) translations)
Note: don't forget that your translation must keep all the original placeholders, such as %1, {name}, {{text}}, unchanged and in the same position. Changing or removing them can either break the text or trigger an error.
4. Save the file as a CSV. Make sure to save it with UTF-8 encoding to avoid issues with special characters.
Now you can apply your translations in the admin or use them in a custom module or theme. Moreover, you can bundle your translation dictionaries into a language pack to share with others.
How to Find Text for Translation Automatically?
You don't have to create translation dictionaries in Magento all the time. Magento developers or theme vendors usually do that to provide translations for phrases and texts there.
If you're a store owner who wants to translate Magento, you might need an easier way to add translations.
That easier way is Magefan that automatically finds all texts for translations for you.
You can then filter them out to specific locales, translate directly in a corresponding panel or export and create a dictionary.
