If you want to create a Magento multi-language store, you need to translate a lot on your store. But before you get to that stage, you must learn about Magento language packs.
What are Magento Language Packs?
Magento 2 language packs are sets of CSV files containing translations for core backend and frontend information in Magento. They cover specific locales, like de_DE for German, or fr_FR for French and are added via Composer or app/i18n directory.
Language packs allow you to translate buttons, labels, system messages, notifications, and email templates quickly and effortlessly. All without the need to edit anything manually.
Besides, they are easy to edit and customise because of their open-source nature.
Key Features
To understand the nature of Magento language packs and learn how to work with them, let's dive into more details about their features.
- CSV-based files — each language pack i18n/locale_name.csv file contains the pairs of original and translated versions. This format makes it easier for you to edit and change some specific text. No need to edit Magento core code.
- Locale-based files — each language pack is tailored to specific language. Then once you assign the package to a specific locale, the system replaces default English text with the translaion from the language pack.
- Store view hierarchy — Magento allows you to create and assign specific language packs to separate store views to create regional experiences. e.g. in case you want to adjust the wording for British and American English, etc.
- Backend and front-end coverage — language packs cover you entire Magento installation. So if you want to change the language of Magento admin panel, use language packs for that too.
- Open source — you don't have to create Magento language packs since most of the locales are already covered and perfected by the community. Find them on platforms like Magento Marketplace or GitHub.
- Customisation — the open source nature allows you to override and edit any translations from the language pack. Adjust it to your brand working or regional dialect easily.
Structure
Magento uses standard module structure for the language packs. So, the key components include:
- Registration.php — registers the language pack as a Magento module.
- Composer.json — declares the name and dependencies.
- i18n/locale_name.csv — the main transaction file that contains translation mappings in this format:
"original string", "translated string"
"original string", "translated string"
"original string", "translated string"
How Language Packs Work in Magento?
Now that you know what language packs cover in Magento, let's see how they actually work.
Stage 1: Activation
Once you install a language pack, you need to enable it by running the following commands:
php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy lanugage_code (optional)
Also, if the translations are not reflected, try clearing the cache:
php bin/magento cache:flush
Stage 2: Configuration
The next step is to make sure the language pack matches a corresponding locale. Otherwise, though the package is enabled, the system won't know what language to serve your backend and frontend in.
For that, go to Stores > Configuration > General > Locale Options and assign a specific Locale to the specific store view.
As soon as you do that, the system will start to reflect a corresponding locale for each frontend and backend user.
Stage 3: Rendering
To render the translations on the right store view, Magento uses the \Magento\Framework\Phrase\Translator class. It identifies text wrapped in the translation functions.
Then the system scans all i18n.csv language packs and searches for a matching translation to replace the original string.
Note: if you can't translate a custom module or theme, it means the developers haven't wrapped specific phrases and texts in translation functions.
Stage 4: Backup and priority
If Magento can't find a matching translation for a specific string, it falls back to the default English translation.
But if you want to prioritise some phrases, just override the global translations by adding custom i18n/locale_name.csv files to your module or theme.
How to Create a Language Pack for Magento?
Although you most likely won't need to create Magento language packs from scratch, let's see what the process looks like. In case you need to customise them with the brand wording or dialects.
1. Create a dictionary for your language pack
root/app/18n/vendor/locale_name
2. Collect the phrase from the translation in a CSV file using the following command:
bin/magento i18n:collect-phrases -o “/app/i18n/vendor/locale_name.csv” -m
Pro tip: specify Magento root directory instead of a specific module or theme to generate the CSV file. The command will find all phrases available in the code.
3. Translate collected phrases and words by opening the CSV file in Google Sheets or Excel.
Note: while translating, change only the second column and pay attention to the original placeholders like %1, {name}, {{text}}. Don't change them or their position, as it can either break the text or throw an error.
4. Register your language pack in the Magento system. For that, create registration.php, language.xml and composer.json files in the language package directory using Magento guidelines.
Creating your own language package allows you to gain full control over your store translations. But if you're not a technical person, this task is close to impossible.
So, sometimes it's just easier to rely on a tool that searches for all texts for you.
How to Install Magento Language Packs?
If creating a language pack is not an option, just get one already available within the Magento community.
You can install Magento language pack either from Magento Marketplace, or by placing your own language pack in a specific folder (i18n) on your instance.
After installation, you just need to turn it on in your store settings and run static content deployment so that translations start rendering.
FAQs
To install a language pack in Magento 2:
1. Login to your Magento server as a system file owner.
2. Go to the Magento root directory.
3. Run the following CLI commands:
composer require vendor/language-pack-en-us
php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy en_US
We use en_US language in the example, replace it with the locale you're installing.
To enable a language pack in Magento 2:
1. Go to Stores > Configuration > General > Locale Options.
2. From the Locale dropdown menu, select the desired language.
3. Once you finish, save the settings and flush the Magento cache.
