Magento 2 Theme Translation: Steps and Best Practices

Magento 2 Theme Translation: Steps and Best Practices

Want to localize your Magento 2 store module for a global audience? Magento 2 Theme Translation provides a seamless shopping experience for customers in different regions and languages.

This tutorial will cover the step-by-step process. It will show how to add translations to your Magento 2 theme.

Key Takeaways

  • Understand the basics of translation in Magento.
  • Understand the process of adding translations to your theme.
  • Learn how to create translation files and implement translations in theme templates.
  • Discover how to test the translations to ensure they appear correctly on the commerce frontend development.

What is Magento 2 Theme Translation?

Magento 2 theme translation involves localizing the text elements of an e-commerce website built on the Magento 2 platform to support multiple languages.

This process ensures that users from different linguistic backgrounds can navigate and understand the content in their preferred language.

Magento uses a translation dictionary approach. Each string or phrase that needs to be translated is stored in translation files. This enhances inclusivity and accessibility and drives growth in international markets.

How To Add Translations in Magento 2 with Translation Extensions?

To add translations to different store views in Magento 2, use - Magento 2 translation extension. It is the easiest and quickest way to do so. It is an alternative to the Magento 2 Translate Inline Tool. The extensions help translate labels, buttons, and short content of up to 250 characters from the admin.

Note: For this tutorial, we have used the Magefan extension. Steps may differ for different extensions. Please refer to the official documentation for your specific extension.

Step 1: Install Magento 2 Translation Extension

You can install this extension using either composer or archive installation methods. To install Translation Plus, follow these steps:

  • Go to your Magefan Account > My Downloads > Install via Composer.

1. Installation via composer (recommended)

  • Start the command-line tool.
  • Navigate to your Magento 2 root directory using the 'cd' command.
  • Run the following command-line interface (CLI) commands:

CLI commands

2. Installation via archive and FTP

  • Download the Translation Extension ZIP archive from the official Magefan website.
  • Unzip and extract files.
  • From the archive, make a copy of the 'app' folder and paste it to your Magento 2 directory.
  • Use 'cd' to navigate to your Magento 2 root directory.
  • Execute the following CLI commands:
php bin/magento setup:upgrade
php bin/magento setup:di: compile
php bin/magento setup:static-content:deploy

archive and FTP commands

Step 2: Create a New Translation

Product page with 'Add to Cart' button

  1. Go to the Admin Panel > System > Tools > Translation by Magefan.

Translation by Magefan

  1. Click on the 'Add Translation' button on the top-right corner of the 'Translation' page.

  2. Include some texts under the 'Original Text'. Add their translated versions to the 'Translate Text' section.

  3. Click on 'Store View' to add this translation.

  4. Set the language of your translated text in the 'Locale' dropdown.

Add Translation

  1. Click on 'Save Translation'.

Modifying Fields

  1. Flush all Magento cache and visit the storefront to review the changes.

Final Result

Note: Choose store views to add different translations to your multi-website. This is if the language is the same in more than one store view.

How To Translate Magento 2 Extension Using Theme Translation Files?

The translations are usually stored in the .csv files on your server. However, you have to build the .csv file if you find no CSV translation file translated for your language.

Note: Remember to disable the Magento 2 cache before starting with the .csv file translation.

Step 1: Set up the Required File for Translation

  1. Go to the Magento 2 admin panel.
  2. Copy the .csv file. Check the example below:


File/Folder Description
'app/design/frontend/' Directory for frontend themes
'i18n' Directory for translation files
'en_US.csv' English (US) translation file
'de_DE.csv' German translation file

Step 2: Translate the phrases accordingly

  1. Ensure the strings in your .csv file start and end with double quotes and are separated with comma [,].

"Add to Cart", "Translated Text"

  1. Change the default theme strings according to your website's requirements, for example:
"My Account","Your Account"
  1. Remember that all the lines are case-sensitive. Copy the phrase exactly as displayed in the "en_US" version.

  2. Look at this example text in the "en_US" magento open source version:

"%s Item(s)","%s Item(s)"

  1. The translated text should appear like this:

"%s Items","%s Product(s)"

  1. Put two double quotation marks to set off a phrase or word by quotation marks.

"String","Translated word"

  1. Use HTML coding to alter your text. For Example:

"Warning!","<strong style="color:red">Attention!</strong>"

Step 3: Save the CSV File in UTF-8 Encoding

  • Different text editors support different alphabets. Remember to save the .csv file in UTF-8 encoding before exiting.

  • For instance, if you edit the file in Excel, convert it into UTF-8 encoding after you finish editing.

How To Apply Different Translations To The Same Element On Various Pages

To apply different translations to the same element on various pages in Magento 2, you need to specify the context of the translation. This ensures that a text string can have different translations depending on where it appears within your store.

Step 1: Identify the Element and Its Context

  1. Determine the exact text string you want to translate.

  2. Identify the different contexts or pages where this text string appears (e.g., product catalog, checkout page).

Step 2: Locate or Create the CSV Translation File

  1. Go to your theme’s i18n directory, usually found at


  1. If an ‘en_US.csv’ file (or appropriate language file) doesn’t exist, create one.

Step 3: Add Contextual Translations

  1. Open the CSV file with a text editor or spreadsheet software.

  2. Add entries for the text string with context-specific prefixes. The format should be:

"Module_Name::Original Text","Translated Text"

Step 4: Save and Upload the CSV File

  1. Save the changes to the CSV file.
  2. Ensure the file is uploaded to the correct directory if you’re working on a local environment and need to deploy it to a live server.

Step 5: Clear Magento Cache

  1. After making changes to translation files, clear the Magento cache to apply the new translations.

  2. You can do this via the Admin Panel: System > Cache Management > Flush Magento Cache. Or using the command line:

bin/magento cache:clean bin/magento cache:flush

Step 6: Verify the Translations

  1. Navigate to the different pages (e.g., catalog and checkout).
  2. Ensure that the translations are correctly applied as specified.

Troubleshooting Common Issues in Magento 2 Theme Translation

Issue Solution
Translations not appearing on the frontend -Verify that the translation files are placed in the correct i18n directory.
- Clear the Magento cache.
- Ensure the correct locale is selected in the store configuration.
Special characters not displaying correctly -Make sure your translation files are saved with UTF-8 encoding.
- Use HTML entities for special characters (e.g., & for &).
Translations conflicting with third-party extensions -Check if the third-party extension has its own translations.
- Override the extension's translations in your theme's i18n directory if needed.

Best Practices for Theme Translations

  1. Keep your translations organized in separate CSV files for each language.
  2. Use a consistent naming convention for your translation files (e.g., fr_FR.csv).
  3. Collaborate with professional translators to ensure accurate and high-quality translations.
  4. Regularly update and maintain your translations as your store content changes.


1. Can I translate the Magento 2 theme without modifying the core files?

Yes, you can add translations to your theme without touching the Magento core files. Create translation files in your theme's i18n directory.

2. How do I handle translations for third-party extensions?

Third-party extensions may have their own translations. Place your own translation files in your theme's i18n directory and override them.

3. Can I use different translations for different store views?

Yes, Magento 2 allows you to set different translations for each store view. You can define translations specific to each store view in the admin panel.

4. How do I ensure my translations are SEO-friendly?

Use descriptive and keyword-rich translations for your content, meta titles, and descriptions. Avoid using machine translations, as they may not be SEO-friendly.

5. Can I contribute translations to the Magento community?

Yes, you can contribute to the Magento community through the Magento Crowdin project. It's a collaborative effort to provide translations for the Magento 2 platform.

6. Can I use custom theme translations for extensions?

Yes, you can add custom translations for Magento 2 extensions. Place the translation files in the extension's i18n folder.

7. How do I verify my translations?

Clear the cache ('php bin/magento cache:clean') after adding translations. Check the frontend of your store to ensure the translations are applied.



Magento 2 theme translations is the process of localizing the text elements within a Magento. It helps users:

  • Get access to international markets and create an inclusive multilingual shopping experience.
  • Incorporate translations to create a more inclusive and accessible online store.
  • Add translations to different store views in Magento 2.
  • Translate labels, buttons, and short content of up to 250 characters from the admin.
  • Apply different translations to the same element on different pages.

Explore Managed Magento hosting for professional translation services to help ensure a seamless multilingual experience for your customers.

Dikshya Shaw
Dikshya Shaw
Technical Writer

Dikshya leverages her content marketing and writing proficiency to deliver fresh, insightful content. Her meticulous research ensures industry expertise and emerging trends within the Magento landscape.

Get the fastest Magento Hosting! Get Started