Soluling home   Document home

Magento Localization and Internationalization

Magento Localization and Internationalization

Magento (Wikipedia) is a popular open source e-commerce platform. It is available as Magento Open Source and as Adobe Commerce. Magento has built-in support for translation files: you can extract the strings of your themes and modules into CSV files and translate them. Soluling Desktop and Soluling Cloud support Magento translation files.

Magento translation files

A Magento translation file is a UTF-8 CSV file that contains one string on each row. The file is named by the locale, for example, en_US.csv. The first column contains the original phrase, and the second column contains the translation. In the original file, the translation is the same as the original phrase.

"Add to Cart","Add to Cart",module,Magento_Catalog
"Shopping Cart","Shopping Cart",module,Magento_Checkout
"You added %1 to your shopping cart.","You added %1 to your shopping cart."

The third and fourth columns are optional. They specify the module that the phrase belongs to. Soluling uses the module name as a part of the context of the string (e.g., Magento_Catalog.Add to Cart), so the same phrase can be translated differently in different modules. If the row has no module, the phrase itself is the context.

Phrases can contain placeholders such as %1 and %2 that Magento replaces with values at run time. Keep the placeholders in the translations. You can change their order if the target language needs it.

When Soluling builds the localized files, it writes the same rows to the localized file but replaces the second column with the translation.

"Add to Cart","Lisää ostoskoriin",module,Magento_Catalog
"Shopping Cart","Ostoskori",module,Magento_Checkout
"You added %1 to your shopping cart.","Lisäsit tuotteen %1 ostoskoriisi."

Extract the strings

Use Magento's i18n tool to collect the phrases of your theme or module into a CSV file.

bin/magento i18n:collect-phrases -o en_US.csv app/code/Vendor/Module

Add the -m option to write the module columns. This is recommended if you collect the phrases of several modules into one file.

bin/magento i18n:collect-phrases -m -o en_US.csv app/code/Vendor

Run the command again whenever you have changed the strings, and update the Soluling project with the new file.

Localization process

You can localize a Magento translation file either in Soluling Desktop or in Soluling Cloud.

Desktop process Desktop process

  1. Start Soluling. Drag the CSV file (e.g., en_US.csv) onto Soluling or click the New from File or Files button and select the file.
  2. If Soluling asks what kind of file it is, select Magento translation file and click OK.
  3. Project Wizard appears. Select the original language and the target languages, for example, Finnish, and complete the wizard.
  4. Translate the project.
  5. Choose Home | Build All to build the localized files. By default, Soluling creates them into the same directory as the original file and names them by the locale, for example, fi_FI.csv.

If the original file already contains translations in the second column, for example, because you started from a file that someone else translated, select the language of the translations on the Options sheet (Language in the translation column). Then Soluling imports those translations into the project. In addition, if the original file is named by the locale (e.g., en_US.csv), Soluling imports the existing translations from the other locale files in the same directory (e.g., de_DE.csv) when you create the project.

Cloud process Cloud process

With Soluling Cloud, you translate the CSV file in your browser: upload the file, translate it in Translate, and download the localized files. You need a Soluling account. See the available Cloud plans.

Create a project

  1. Sign in at www.soluling.com and open Cloud > Dashboard for Projects, Users and Terminology.
  2. Click Add a new project, then Select files and pick en_US.csv, or drag and drop the file onto the page. Click Create.
  3. On the next page, check the project's Name. It defaults to the file's name.
  4. Set the Original language to English (United States).
  5. Under Target languages, check the languages you want to translate to, for example, Finnish (Finland) and German (Germany).
  6. Under Source type, select Magento translation file (.csv). A Magento file is also a valid generic CSV file, so make sure you pick the Magento parser.
  7. Click Create. The project appears on the dashboard, and its status changes to Ready once the file has been processed.

Translate the project

Click the project's green Translate button on the dashboard. Translate opens the project, and you can type the translations into the grid. Machine translation suggestions, translation memory, and spell checking are available there. You do not have to finish every language before moving on to the next step.

Get the localized files

  1. In Translate's top bar, click the project's name. It opens the project's Manage page, the same page that the project's Manage button on the dashboard opens.
  2. If you have translated something since the localized files were last built, the page says Localized files need to be built. Click Build localized files and wait until it finishes.
  3. The Files section lists en_US.csv with a download button for each target language. Save each localized file with the name of its locale, for example, fi_FI.csv.

Update the project

When you have collected the phrases again, upload the new en_US.csv, translate what is new or changed, and download the localized files again. On the dashboard, click the project's Update file button (the upload arrow), select the new file or drop it onto the page, and click Update. Existing translations are kept, so you only translate the phrases that were added or changed.

The dashboard is one of four ways to use Soluling Cloud. You can also use the SoluCLI command-line tool, Soluling Desktop, or SoluMake, which can run the update and build steps in your build pipeline. See the Cloud tutorial for all of them.

Use the localized files

Magento looks for the translation files by the locale of the store view. There are two common ways to deploy the localized files:

Then set the locale of the store view to the language (Stores > Configuration > General > Locale Options), and clean the cache so that Magento loads the new translations.

bin/magento cache:clean

If the store runs in production mode, deploy the static content for the new locale too, for example, bin/magento setup:static-content:deploy fi_FI.

Configuring Magento localization

You can configure how to localize your Magento CSV file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.