Translator

Basic Usage

The translator 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.

$translator = new Zend\I18n\Translator\Translator();

echo $translator->translate('car'); // car
echo $translator->translate('train'); // train

Adding Translations

Two options exist for adding translations to the translator:

• Add every translation file individually; use this for translation formats that store multiple locales in the same file.
• Add translation files based on a pattern; use this for formats that use one file per locale.

Add a Single File

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

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

where the arguments are:

• $type: the name of the format loader to use; see the next section for details.
• $filename: the file containing translations.
• $textDomain: a "category" name for translations. If this is omitted, it defaults to "default". Use text domains to segregate translations by domain.
• $locale: the language strings are translated from; this argument is only required for formats which contain translations for single locales.

Example

$translator = new Zend\I18n\Translator\Translator();
$translator->addTranslationFile(
    Zend\I18n\Translator\Loader\PhpArray::class,
    __DIR__ . '/languages/de_DE.php'
);

Add Multiple Files via Pattern

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:

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

where the arguments are:

• $type: the name of the format loader to use; see the next section for details.
• $baseDir is a directory containing translation files.
• $pattern is an sprintf()-formatted string describing a pattern for locating files under $baseDir. The $pattern should contain a substitution character for the $locale — which is omitted from the addTranslationFilePattern() call, but passed whenever a translation is requested. Use either %s or %1$s in the $pattern as a placeholder for the locale. As an example, if your translation files are located in /var/messages/<LOCALE>/messages.mo, your pattern would be /var/messages/%s/messages.mo.
• $textDomain: a "category" name for translations. If this is omitted, it defaults to "default". Use text domains to segregate translations by domain.

Example

$translator = new Zend\I18n\Translator\Translator();
$translator->addTranslationFilePattern(
    Zend\I18n\Translator\Loader\PhpArray::class,
    __DIR__ . '/languages',
    'translation-%s.php'
);

Supported formats

The translator supports the following major translation formats:

• PHP arrays
  • File
  • Memory
• Gettext
• INI

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.

Examples

PHP Array

return [
    // Message => Translation
    'car'   => 'Auto',
    'train' => 'Zug',
];

INI

Normal syntax:

; Message
identifier1.message = "car"
; Translation
identifier1.translation = "Auto"

identifier2.message = "train"
identifier2.translation = "Zug"

Simple syntax:

; Message
identifier1[] = "car"
; Translation
identifier1[] = "Auto"

identifier2[] = "train"
identifier2[] = "Zug"

Setting a locale

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

$translator = new Zend\I18n\Translator\Translator();
$translator->setLocale('de_DE');

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:

$translator = new Zend\I18n\Translator\Translator();
$translator->setFallbackLocale('en_EN');

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 identifier 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 set here, as by default the locale is taken from the locale set in the translator.

$translator = new Zend\I18n\Translator\Translator();
echo $translator->translate('car');

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.

$translator = new Zend\I18n\Translator\Translator();
echo $this->translatePlural('car', 'cars', 1); // 'Auto'
echo $this->translatePlural('car', 'cars', 4); // 'Autos'