vendor/zendframework/zend-i18n/doc/book/translation.md

   1 # Translation
   2
   3 zend-i18n comes with a complete translation suite supporting all major formats
   4 and including popular features such as plural translations and text domains. The
   5 Translator subcomponent is mostly dependency free, except for the fallback to a
   6 default locale, where it relies on the PHP's intl extension.
   7
   8 The translator itself is initialized without any parameters, as any
   9 configuration to it is optional. A translator without any translations will do
  10 nothing but return all messages verbatim.
  11
  12 ## Adding translations
  13
  14 Two options exist for adding translations to the translator:
  15
  16 - Add every translation file individually; use this for translation formats that
  17   store multiple locales in the same file.
  18 - Add translation files based on a pattern; use this for formats that use one
  19   file per locale.
  20
  21 To add a single file to the translator, use the `addTranslationFile()` method:
  22
  23 ```php
  24 use Zend\I18n\Translator\Translator;
  25
  26 $translator = new Translator();
  27 $translator->addTranslationFile($type, $filename, $textDomain, $locale);
  28 ```
  29
  30 where the arguments are:
  31
  32 - `$type`: the name of the format loader to use; see the next section for
  33   details.
  34 - `$filename`: the file containing translations.
  35 - `$textDomain`: a "category" name for translations. If this is omitted, it
  36   defaults to "default". Use text domains to segregate translations by context.
  37 - `$locale`: the language strings are translated from; this argument is only
  38   required for formats which contain translations for single locales.
  39
  40 > ### Text domain and locale are related
  41 >
  42 > For each text domain and locale combination, there can only be one file
  43 > loaded. Every successive file would override the translations which were
  44 > loaded prior.
  45
  46 When storing one locale per file, you should specify those files via a pattern.
  47 This allows you to add new translations to the file system, without touching
  48 your code. Patterns are added with the `addTranslationFilePattern()` method:
  49
  50 ```php
  51 use Zend\I18n\Translator\Translator;
  52
  53 $translator = new Translator();
  54 $translator->addTranslationFilePattern($type, $baseDir, $pattern, $textDomain);
  55 ```
  56
  57 where the arguments are roughly the same as for `addTranslationFile()`, with a
  58 few differences:
  59
  60 - `$baseDir` is a directory containing translation files.
  61 - `$pattern` is an `sprintf()`-formatted string describing a pattern for
  62   locating files under `$baseDir`. The `$pattern` should contain a substitution
  63   character for the `$locale` &mdash; which is omitted from the
  64   `addTranslationFilePattern()` call, but passed whenever a translation is
  65   requested. Use either `%s` or `%1$s` in the `$pattern` as a placeholder for
  66   the locale. As an example, if your translation files are located in
  67   `/var/messages/<LOCALE>/messages.mo`, your pattern would be
  68   `/var/messages/%s/messages.mo`.
  69
  70 ## Supported formats
  71
  72 The translator supports the following major translation formats:
  73
  74 - PHP arrays
  75 - Gettext
  76 - INI
  77
  78 Additionally, you can use custom formats by implementing one or more of
  79 `Zend\I18n\Translator\Loader\FileLoaderInterface` or
  80 `Zend\I18n\Translator\Loader\RemoteLoaderInterface`, and registering your loader
  81 with the `Translator` instance's composed plugin manager.
  82
  83 ## Setting a locale
  84
  85 By default, the translator will get the locale to use from ext/intl's `Locale`
  86 class. If you want to set an alternative locale explicitly, you can do so by
  87 passing it to the `setLocale()` method.
  88
  89 When there is no translation for a specific message identifier in a locale, the
  90 message identifier itself will be returned by default. Alternately, you can set
  91 a fallback locale which is used to retrieve a fallback translation. To do so,
  92 pass it to the `setFallbackLocale()` method.
  93
  94 ## Translating messages
  95
  96 Translating messages is accomplished by calling the `translate()` method of the
  97 translator:
  98
  99 ```php
 100 $translator->translate($message, $textDomain, $locale);
 101 ```
 102
 103 The message is the message identifier to translate. If it does not exist in the
 104 loader, or is empty, the original message ID will be returned. The text domain
 105 parameter is the one you specified when adding translations. If omitted, the
 106 "default" text domain will be used. The locale parameter will usually not be
 107 used in this context, as by default the locale is taken from the locale set in
 108 the translator.
 109
 110 To translate plural messages, you can use the `translatePlural()` method. It
 111 works similarly to `translate()`, but instead of a single message, it takes a
 112 singular value, a plural value, and an additional integer number on which the
 113 returned plural form is based:
 114
 115 ```php
 116 $translator->translatePlural($singular, $plural, $number, $textDomain, $locale);
 117 ```
 118
 119 Plural translations are only available if the underlying format supports the
 120 translation of plural messages and plural rule definitions.
 121
 122 ## Caching
 123
 124 In production, it makes sense to cache your translations. This not only saves
 125 you from loading and parsing the individual formats each time, but also
 126 guarantees an optimized loading procedure. To enable caching, pass a
 127 `Zend\Cache\Storage\Adapter` to the `setCache()` method. To disable the cache,
 128 pass a `null` value to the method.