Translation

Prerequisites

Basics

Every string in a PHTML template must use Magento’s translation method:

<?php
echo $this->__('Translate me');
echo $this->__('Hello %s', $name);
echo $this->__('My name is %s. I am %s years old.', $name, $age);
echo $this->__('My name is %2$s. I am %1$s years old.', $age, $name);
?>

Core templates are always written in English (US).

When to use translation

Do not use translation to avoid modifying a template. Editing strings directly in templates is usually preferred:

  • Less abstraction between code and output.
  • No risk of translation collisions.
  • Easily locate the template by searching for the string.

Internationalization

Multi-language support is the obvious use case.

String replacement

The default store view’s locale may include a translation file. The reason might not be obvious.

The use case is replacing (not translating) strings that appear throughout the website. Using the translation method to alter strings while rendering is more efficient/consistent than modifying/maintaining multiple templates.

Translation methods

Inline method

Inline translation is never used. Here’s why:

  • Translations stored in the database are hard to sync between environments.
  • No interface to view or mass edit strings being translated inline.
  • Requires translate.js script be added to frontend, which is bloat. Certain interactions in Magento’s JS still require this (stupidly). It can otherwise be removed.

CSV method

Each locale will have a unique translation file.

/app/design/frontend/{package}/{theme}/locale/en_US/translate.csv

Login,Sign In
Logout,Sign Out
"Red, green, blue","Use double quotes"
State/Province,State
Zip/Postal Code,ZIP Code

Always order translations alphabetically by the first string.

References

Grouping CSV translations

Grouping translations into core overrides and custom phrases helps keep them organized. For internationalization this helps document changes to templates.

~~~,~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~,Magento core phrases translated for this locale.
~~~,~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Login,Sign In
Logout,Sign Out
"Red, green, blue","Use double quotes"
State/Province,State
Zip/Postal Code,ZIP Code



~~~,~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~,Custom phrases that exist only in this theme.
~~~,~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Call 456-789-1234,Call 456-789-1234

More from the “Frameworks” stack