How to translate a Magento Commerce store

Magento is an open-source ecommerce platform, based on PHP and MySQL, and was first released in 2008. It’s currently owned by Adobe, Inc. and was recently rebranded as Adobe Commerce. Its current market share is stable but relatively low, between 2% and 3% of all online stores, but it is usually preferred for high traffic sites.

 Choosing your Magento localization strategy

In order to give you an extensive overview of the work environment, this guide will deal with just one of the two main approaches to translate a Magento store. We chose this approach because Magento lets you easily export most of your ecommerce contents as plain CSV files, which is a very translation-friendly format. Admittedly our chosen approach is the slower one, but allows you to better control the whole process. So if time is not of the essence, you can translate your Magento store following four basic steps:

1. Preparing your Magento installation to be multilingual
2. Extracting the text contents of the store
3. Translating the resulting files
4. Publishing your translations

The alternative approach consists of using a third-party localization connector, such as Smartcat, Weglot, Memsource, and many others. This approach may require less manual effort, but you will need to rely on the third-party vendor for support and future updates. For more information about this approach, refer to our report on Translating websites with translation proxies.

Prepare Magento Open Source to make it multilingual

First of all let’s review where the translatable contents are located in your Magento system:

• Back-end and system messages
• Themes
• CRM contents
  • Pages
  • Blocks
• Dynamic content
  • Attributes
  • Categories
  • Products
• Extensions
• External files
  • Email templates
  • Images
  • PDF
  • Video
• Embedded code

Magento’s default backend and system messages are already translated into many languages by the community and are publicly available as “language packages” from the official Magento Internationalisation Github repository.

Therefore, to start the localisation process:

1. Download and add the required target language package(s).
2. Add a new store view for your target language(s)
3. Update the locale configuration to the target country’s preferences for currency, units of measure, etc.

Adding a Language Package in Magento

As an example, here is the procedure to install the Italian language package:

1. Download the Italian language package file it_IT.csv from https://github.com/magento-l10n/language-it_IT.
2. Upload its contents via FTP to the following folder (create it if required):
   [root]/App/i10n/it_IT/.
3. Flush Magento Cache to apply the changes to the frontend.
4. To display Magento’s backend in Italian, change the display language at a profile level, if required.

You can always update the language package by editing the it_IT.csv file and upload it again to the same folder and flushing the cache.

Magento will try to apply the translation dictionary to all text displayed in the frontend. This means that the same word will always be translated in the same way, so you should be extra careful to avoid the wrong translation being applied in a different context for words with more than one meaning.

One way to solve this is to translate the same element in different ways for different modules, by editing the original CSV file, which looks like this:

"Add to Cart", "Aggiungi al carrello"

And specify the module for each translation variant:

"Add to Cart", "Aggiungi al carrello", module, Magento_Review
"Add to Cart", "Aggiungi al carrello della spesa", module, Magento_Catalog

If you are not sure what module requires a certain translation, or there are still more than one translation inside the same module, you need to change the translation of the element from the backend (see below), because it will always have the highest priority over the translation dictionaries. Refer to this page to learn more: https://developer.adobe.com/commerce/frontend-core/guide/translations/dictionary/.

As an alternative, Magento offers the Inline translation feature. Inline translation is an easy way to translate the store contents directly from the frontend, by clicking on each phrase. It can be enabled from Stores → Configuration → Advanced → Developer → Inline translation. Please refer to [https://docs.magento.com/user-guide/system/translate-inline.html]https://docs.magento.com/user-guide/system/translate-inline.html) for more information.

Adding a Store View for a new Language in Magento

Once the new language has been added to Magento, a new store view must be created, so that a language switcher is placed in the frontend. Follow these steps to add a new store view:

1. Login to your admin panel and go to Stores → Settings → All Stores.
2. Click Create Store View at the top right.
3. Fill in the form, as follows:
   Store is the parent store of the new view.
   Name is the new store view name, which will be displayed in the language switcher, e.g. Italiano.
   Code is the view ID and must be lower case, e.g. italian.
4. Enable the new view.
5. Enter a Sort Order number (optional) to change the sequence in which this view is listed
6. Save the new Store View.

Updating the Locale Configuration of a Store View in Magento

The new store configuration must be updated to reflect the new locale, i.e. country, region, unit of measure, currency etc. Proceed as follows:

1. Go to Store → Settings → Configuration.
2. Select the store view for the language you want to configure from the upper left dropdown menu.
3. In the General panel, uncheck the Use Website boxes besides the fields and set the drop down menus to the appropriate values for Country, Locale, etc.
4. Select Currency Setup, uncheck the Use Website boxes besides the fields and select the new currency, for example Euro.
5. Save.
6. Update the currency exchange from Stores → Currency → Currency Rates if required.

How to Translate Magento Themes

Similarly to what we’ve seen when adding a language package, theme texts can be translated by adding a translation dictionary, which is a CSV file located in a specific folder of the theme. If the translation dictionary for your target language is not available, you can generate a translation dictionary and translate it into your target language(s).

1. Create the required folder structure on the theme, adding the directory
   [magento_root]/app/design/frontend/[vendor_name]/[theme_name]/i18n.
2. Extract the translatable text into CSV format: open the command line terminal and launch the bin/magento i18n:collect-phrases command, followed by the appropriate options (output file, folder to translate).
3. The resulting file will have two columns in the source language, the first should remain untranslated, while the second should be translated in the target language.
4. Rename the translated file using the ISO code for the target language, for example it_IT.csv for Italian (Italy)
5. Upload the new CSV file to the folder created at the beginning.
6. Flush the cache.

How to Translate Magento Store Contents

The translatable contents in a Magento online store can be divided in two categories: static contents and dynamic contents.

Static contents are typically menus, pages (i.e. the home page, about us page, etc.) and blocks, and they are linked by Widgets. Each widget is basically just a set of options that defines the way a certain block is displayed on a certain page. They can only be translated from the backend and the same page in different languages must share the same URL Key value.

Dynamic contents, on the other hand, are the product names, descriptions and meta data, together with their attributes and categories. They can be translated either from the backend, or in CSV format.

Translating Magento Pages from the Backend

Pages can be translated manually from the backend as follows:

1. Go to Content → Elements → Pages.
2. Open the source page in edit mode, set the Store View to the appropriate language, then:
   1. Open a new document in a plain text editor.
   2. Copy-paste all the translatable text to your text editor, such as Title, Header, meta data...
   3. Click Show/Hide Editor to display the HTML code view and copy-paste the code to the open document in your text editor.
   4. Save the document as HTML and translate it.
3. Click the Save menu and select Save & Duplicate.

After completing the translation:

1. Go back to Content → Elements → Pages
2. Open the duplicated page in edit mode.
3. Copy-paste the translated Page Title, Page Header and HTML code from the target file to the corresponding fields in the Content box.
4. Leave the source URL Key and copy-paste the translated meta data in the SEO box.
5. Choose the store view for the new page.
6. Save.

Translating Magento Blocks from the Backend

Blocks are also text containers to display inside different pages. To translate their contents, proceed as follows:

1. Go to Content → Elements → Blocks.
2. Open the source block in edit mode, set the Store View to the appropriate language, then:
   1. Open a new document in a plain text editor.
   2. Copy-paste the Block Title and click Show/Hide Editor to display the HTML code view, and copy-paste the code to the open document in your text editor.
   3. Save the document as HTML and translate it.
3. Click the Save menu and select Save & Duplicate.

After completing the translation:

1. Go back to Content → Elements → Blocks.
2. Open the duplicated block.
3. Copy-paste the translated Block Title and HTML code from the target file to the Editor box. Change the identifier if required.
4. Save.

Setting up a New Widget in Magento

Now you need to set up a widget that links the each new block in the target language(s) to the corresponding page. Unlike pages and blocks, widgets can’t be duplicated, so when you have the target block in place, you need to create a new widget and apply the same options as the source language, except the Store View it is assigned to. Proceed as follows:

1. Go to Content → Elements → Widgets.
2. Open the widget which links the original block to the original page and change the Store View assignment to the source language, if required, and save.
3. Open another browser tab, go to Content → Elements → Widgets and create a new widget.
4. Apply the same Type and Layout updates as the original widget, type the name of the widget in the Title field and select the Store View for the appropriate language.
5. Save the new widget.
6. Flush the Magento cache to apply the changes.

Translating Magento Dynamic Contents From the Backend

As above, product names, descriptions etc. can be translated from the backend. But first, you will probably want to translate product-related items that are usually fixed, such as attributes and categories.

Translating Magento Attributes and Categories

Attributes are normally the properties of the products so that customers can choose between product variants such as color, size, weight, material etc. Therefore you will have to translate the name of the attribute and each variant, as follows:

1. Go to Stores → Attributes → Product.
2. In the table, click the attribute to be translated.
3. In the left panel, click Properties and enter a translated label for each attribute.
4. Click Manage Labels and enter a translated attribute name for each store view.
5. Save.

Categories, on the other hand, are a way to group products by type, for example Fiction, Non-Fiction, Novel, Poetry, etc… Each category and subcategory must be translated separately, as follows:

1. Go to Catalog → Categories
2. Select the appropriate store view for your target language.
3. Click the category you want to translate and uncheck the Use Default Value box under the Category name.
4. Type the translated category name in the same field.
5. Save.

Translating Magento Products and Descriptions

Every item in the catalog can be opened and edited directly from the backend, making sure that the correct Store view is selected.

1. Go to Catalog → Products and click on the item you want to translate
2. Select your target language from the upper left dropdown menu
3. Uncheck the Use Default View box under the Product name and edit the name.
4. Translate the rest of the product texts, description, meta data, etc.
5. Save.

Translating Magento Products and Descriptions through Export/Import

To translate the whole product catalog at once, you need to export it in CSV format and translate it outside Magento.

To start the products export, proceed as follows:

1. Go to System → Data transfer → Export.
2. Select Products as Entity Type.
3. Exclude the attributes that lack translatable text.
4. Select CSV as Export File Format.
5. Click Continue.
6. Download the Export file from the box at the bottom.

After translating the file, make sure that every cell in the column store_view_code contains the Store View ID that was set at the beginning when adding the new Store View – in our case italian. To import it to Magento proceed as follows:

1. Go to System → Data transfer → Import.
2. Select Products as Entity Type.
3. Select Add/Update as Import Behaviour.
4. Browse for the translated file and click Check Data at the top right.
5. Click Import or edit the file to correct any errors and repeat.

How to Translate Magento Email and Newsletter Templates

Default email texts are already translated in the target language package, but if the templates were customised, you will need to generate a translation dictionary for each target language and translate it.

1. Extract the translatable text into CSV format: open the command line terminal and launch the bin/magento i18n:collect-phrases command, followed by the appropriate options (output file, folder to translate).
2. The resulting file will have two columns in the source language, the first should remain untranslated, while the second should be translated in the target language.
3. Rename the translated file using the ISO code for the target language, for example it_IT.csv for Italian (Italy)
4. Upload the new CSV file to the corresponding folder.
5. Flush the cache.

Magento Localization Plugins

There are several third-party translation connectors for Magento, and they are usually linked to a specific vendor. The most popular are:

• RWS Language Cloud
• Smartcat
• Translations.com GlobalLink Magento Adaptor
• Lingotek
• Across Language Server
• Wordbee Beebox
• Memsource
• Weglot

Please refer to the relevant documentation to learn more.

Recap

We have seen two approaches to localising a Magento store. The first is more hands-on and time consuming, but grants full control over the whole localization process. Here we have reviewed how to manually extract the text of your ecommerce store for translation and how to publish it in other languages.

The alternative approach, on the other hand, consists of using a localization connector and can be more straightforward, because most of the text extraction is done automatically. But you will depend on a third-party vendor for translation management, support and updates, so you need to carefully ponder all the pros and cons.