zend-i18n comes with a complete translation suite supporting all major formats and including popular features such as plural translations and text domains. The Translator subcomponent is mostly dependency free, except for the fallback to a default locale, where it relies on the PHP's intl extension.

The translator itself is initialized without any parameters, as any configuration to it is optional. A translator without any translations will do nothing but return all messages verbatim.

Adding translations

To options exist for adding translations to the translator:

To add a single file to the translator, use the addTranslationFile() method:

use Zend\I18n\Translator\Translator;

$translator = new Translator();
$translator->addTranslationFile($type, $filename, $textDomain, $locale);

where the arguments are:

For each text domain and locale combination, there can only be one file loaded. Every successive file would override the translations which were loaded prior.

When storing one locale per file, you should specify those files via a pattern. This allows you to add new translations to the file system, without touching your code. Patterns are added with the addTranslationFilePattern() method:

use Zend\I18n\Translator\Translator;

$translator = new Translator();
$translator->addTranslationFilePattern($type, $baseDir, $pattern, $textDomain);

where the arguments are roughly the same as for addTranslationFile(), with a few differences:

Supported formats

The translator supports the following major translation formats:

Additionally, you can use custom formats by implementing one or more of Zend\I18n\Translator\Loader\FileLoaderInterface or Zend\I18n\Translator\Loader\RemoteLoaderInterface, and registering your loader with the Translator instance's composed plugin manager.

Setting a locale

By default, the translator will get the locale to use from ext/intl's Locale class. If you want to set an alternative locale explicitly, you can do so by passing it to the setLocale() method.

When there is no translation for a specific message identifier in a locale, the message identifier itself will be returned by default. Alternately, you can set a fallback locale which is used to retrieve a fallback translation. To do so, pass it to the setFallbackLocale() method.

Translating messages

Translating messages is accomplished by calling the translate() method of the translator:

$translator->translate($message, $textDomain, $locale);

The message is the message identifier to translate. If it does not exist in the loader, or is empty, the original message ID will be returned. The text domain parameter is the one you specified when adding translations. If omitted, the "default" text domain will be used. The locale parameter will usually not be used in this context, as by default the locale is taken from the locale set in the translator.

To translate plural messages, you can use the translatePlural() method. It works similarly to translate(), but instead of a single message, it takes a singular value, a plural value, and an additional integer number on which the returned plural form is based:

$translator->translatePlural($singular, $plural, $number, $textDomain, $locale);

Plural translations are only available if the underlying format supports the translation of plural messages and plural rule definitions.


In production, it makes sense to cache your translations. This not only saves you from loading and parsing the individual formats each time, but also guarantees an optimized loading procedure. To enable caching, pass a Zend\Cache\Storage\Adapter to the setCache() method. To disable the cache, pass a null value to the method.