129 lines
5.0 KiB
Markdown
129 lines
5.0 KiB
Markdown
|
# Translation
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
To add a single file to the translator, use the `addTranslationFile()` method:
|
||
|
|
|
||
|
|
```php
|
||
|
|
use Zend\I18n\Translator\Translator;
|
||
|
|
|
||
|
|
$translator = new 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 context.
|
||
|
|
- `$locale`: the language strings are translated from; this argument is only
|
||
|
|
required for formats which contain translations for single locales.
|
||
|
|
|
||
|
|
> ### Text domain and locale are related
|
||
|
|
>
|
||
|
|
> 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:
|
||
|
|
|
||
|
|
```php
|
||
|
|
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:
|
||
|
|
|
||
|
|
- `$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`.
|
||
|
|
|
||
|
|
## Supported formats
|
||
|
|
|
||
|
|
The translator supports the following major translation formats:
|
||
|
|
|
||
|
|
- PHP arrays
|
||
|
|
- 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.
|
||
|
|
|
||
|
|
## 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:
|
||
|
|
|
||
|
|
```php
|
||
|
|
$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:
|
||
|
|
|
||
|
|
```php
|
||
|
|
$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.
|
||
|
|
|
||
|
|
## Caching
|
||
|
|
|
||
|
|
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.
|