Magento Translation, Step Zero: What Must Be Translated?
Magento Translation, Step Zero: What Must Be Translated?

Magento Translation, Step Zero: What Must Be Translated?

Published October 24, 2014 in Development
Classy Llama Magento Custom Reports Blog
Custom Reports in Magento with Clean_SqlReports
September 24, 2014
Debugging Complex Problems
November 18, 2014

Internationalization is an increasingly important consideration for Magento merchants developers looking to expand market penetration and increase usability. A significant part of this effort is realized in the form of maintaining translations for multiple locales – quite the undertaking, in spite of Magento’s robust localization capabilities.


However, a journey of a thousand miles begins with a single step, and this initial step can be particularly daunting. What must be translated?

Ideally, every string ever used, be it backend or frontend, would be documented so that an exhaustive list is always available of material scheduled for translation. In practice, however, this is rarely the case – maybe the site or module wasn’t initially slated for an international market or the ROI was difficult to justify. Because of this, orphan strings with no record of their existence are very common and a barrier to internationalization.

Wouldn’t it be nice to have a mechanism to retroactively examine a site or module and perform a translation gap analysis?


One approach to ferreting out untranslated strings is to modify the translation tool itself to report untranslated strings as they are encountered. This is often expressed as a quick hack to the translation classes whereby strings are logged, then the changes reverted.

The basic idea is solid, but the execution is essentially a transient hack – requiring repeated discovery and implementation, and is prone to oversights.

After a recent internationalization-intensive project involving several countries and localizations, I attempted to formalize this approach into a robust module.

Translation path

When calling the familiar __() method (whether from a block, helper, controller, etc), Mage_Core_Model_Translate::translate() is invoked to do the actual heavy lifting.


After doing some heuristics to determine exactly what module and code to use for context, Mage_Core_Model_Translate::_getTranslatedString() takes over.


If a translation by either code or text exists, then it is returned – otherwise, the key (untranslated string) is returned.


The Mage_Core_Model_Translate::_getTranslatedString() method offers a perfect opportunity to detect strings with no translation and record them.

String Detection

Unfortunately, there is no event present which can be observed to accomplish this detection, so the model must be rewritten. Using the lightest touch possible for such a fundamental model, the string is preprocessed before translation to determine if it is missing translations for interesting locales.


This simple change allows the module to collect untranslated strings, which, for performance sake, are batched up and flushed to the database in a single query after the page is rendered. All that is required to perform this collection is to enable the module in the system configuration, and browse the site – a perfect scenario for stage sites during ongoing UAT.

Multiple Locales

If a merchant or developer is concerned about translation gaps for one locale, he is likely also concerned about several others. This is facilitated by the loop in _checkTranslatedString() which iterates over multiple locales which are ultimately retrieved from the system configuration.

To check the status of translations other than the currently selected locale, EW_UntranslatedStrings_Helper_Data::isTranslated() performs evaluations independent of current store configuration, aided by getTranslator() which provides ready-to-go translator models for any locale and store ID.

EW_UntranslatedStrings_Helper_Data::isTranslated() and getTranslator()

While it requires a few more rewritten methods on the translator model, this feature allows a store owner or developer to quickly assemble a gap analysis of multiple locales at once.


Although simple in concept, there are several optional tweaks that can make this feature much more useful for efficient string collection.

This module adds a new system configuration section which can be found at Advanced -> Developer -> Untranslated Strings.

System Configuration Screenshot

These options allow several powerful options for customizability. For example

  • Admin translation gaps can be ignored – useful to enable for all websites, but purposely omit admin strings.
  • Matching translation key/value pairs can be either logged or ignored. This accommodates either of the following scenarios:
    • Complete translation gap analysis, where strings which are represented but not actually translated are logged – useful for merchant site evaluation.
    • String representation gap analysis, where only strings which are not represented at all are logged – useful for module developers who only wish to maintain a list of strings and are not concerned with actual translation.
  • Translation code exclusion patterns which omit some strings from the log. Magento has many native translation gaps, and the translation status of some modules may be irrelevant to a given store. This allows final users to tweak the signal-to-noise ratio to ensure efficient use of resource when evaluating untranslated strings.
  • Batch locale translation gap analysis. As mentioned before, this allows the evaluation of several locales at one time, greatly reducing the time required to collect an exhaustive list of strings.


Even the most robust untranslated string detection is useless if the results are not easily accessible and actionable.

To this end, there are two new reports which are now available at Reports -> Untranslated Strings in the main admin menu.

  • Untranslated Strings Summary: this provides an overview of translation gaps by locale and store, and allows the ability to purge or truncate untranslated strings.
  • Untranslated Strings Report: this provides a detailed view of untranslated strings and is filterable by locale, store, popularity, etc.

Additionally, the Untranslated Strings Report allows strings to be exported to CSV file. Combined with its filtering capabilities, this allows a merchant or developer to effectively manage the strings and provide them to translation teams, along with all important context.

Untranslated Strings Report Screenshot


Viewing the untranslated strings report as a sort of “to-do list”, the summary view allows merchants or developers to curate the remaining untranslated strings. In particular, the strings associated with a given locale and store can be truncated (individually or en masse), cleaning the slate and allowing a fresh set of strings to be collected.

Untranslated Strings Summary Screenshot

More powerful, however, is the purge option. Exercising this option on a locale and store (or group of these, via the mass action functionality) causes the module to reevaluate the translation status of associated strings, removing any which are now considered translated according to the system configuration settings.

After adding translations to address gaps, this feature allows merchants and developers to cull strings which are no longer relevant, ensuring that the untranslated string list is always actionable.

Where to go from here (caveats)

While this module goes a long way to formalize a former “hacky” process, there is always room to improve. Some particular things to keep in mind:

  • This module only assists with strings which are wrapped in translate calls – if strings are simply never translated, there is no way to detect them. On the same token, strings which are meant to be translated using admin store scopes (such as product attributes, CMS blocks, etc) are not evaluated.
  • The module introduces a small to moderate performance overhead depending on the number of locales to be evaluated and the number of untranslated strings. Fortunately, this is only realized if the functionality is enabled in system configuration.
  • As with Magento’s inline translation tool, the module works best if translation and block caches are disabled.
  • Like the shoemaker’s wife, the module itself has a few translation gaps …

Where to get it

If you’d like to get your hands on this open source module and take the first step toward internationalization, you can find it on Github:

As stated in the readme, it’s easily installed via modman. Use it wisely!

Interested in building an international e-commerce store or looking to upgrade the one you have? Let us know on our contact form!


  1. Michael says:

    What’s the strategy for going forward when all the untranslated strings are found. Preferably we’d like to keep the CSV in git and then dump them into some locale dir in the Magento hierarchy. But I guess you’ll need to know where themes, and plugins read their CSV locale files from?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Most Recent PostsView all
July 26, 2021

Simplified shopping = Higher Conversions for Marlow White

Overview Since 1879, Marlow White has been dedicated to helping our nation’s best look their best by providing our military and first responders with the highest […]
July 19, 2021

The biggest online fraud trend of 2021? More fraud!

Like almost every aspect of life, the world of online fraud can be viewed through the lens of “before COVID-19” and “after COVID-19.” The stunning and […]
July 13, 2021

A New Customer Experience for DisplayIt Using Celigo

Overview DisplayIt offers fully customizable exhibit booths and tradeshow displays for customers around the world. Their website is used by thousands of merchants each year to […]