Компонент Translation

Компонент Translation

Компонент Translation предоставляет инструменты для интернационализации вашего приложения.

Установка

1
$ composer require symfony/translation

Также вы можете клонировать репозиторий https://github.com/symfony/translation.

Note

Если вы устанавливаете этот компонент вне приложения Symfony, вам нужно подключить файл vendor/autoload.php в вашем коде для включения механизма автозагрузки классов, предоставляемых Composer. Детальнее читайте в этой статье.

See also

Эта статья объясняет как использовать функции Translation как независимого компонента в любом приложении PHP. Прочитайте статью Переводы для понимания как интернационализировать и управлять локалями пользователя в приложениях Symfony.

Построение переводчика

Главная точка доступа компонента Translation - Translator. До того, как вы сможете его использовать, вам нужно его сконфигурировать и загрузить сообщения для перевод (называемые каталогами сообщений).

Конфигурация

Конструктор класса Translator требует одного аргумента: локали:

1
2
3
4
use Symfony\Component\Translation\Translator;
use Symfony\Component\Translation\MessageSelector;

$translator = new Translator('fr_FR');

Note

Локаль, установленная здесь, это локаль для использования по умолчаню. Вы можете переопределить эту локаль при переводе строк.

Note

Термин локаль грубо говоря относится к языку и стране пользователя. Это может быть любая строка, которую исползует ваше приложение для работы с переводами и другими различиями форматов (например, формат валюты). Рекомендуется использовать код языка ISO 639-1, потом нижнее подчёркивание (_), потом код страны (например, fr_FR для французского / Франции).

Загрузка каталогов сообщений

Сообщения хранятся в каталогах сообщений внутри класса Translator. Каталог сообщений является чем-то вроде словаря переводов для конкретной локали.

Компонент Перевод использует классы Загрузчика для загрузки каталогов. Вы можете загружать несколько источников для одной локали, которые потом можно комбинировать в один каталог.

Компонент поставляется с некоторыми Загрузчиками по умолчанию и вы можете также создавать ваш собственный Загрузчик. Загрузчики по умолчанию:

  • ArrayLoader - для загрузки каталогов из PHP массивов.
  • CsvFileLoader - для загрузки каталогов из CSV файлов.
  • IcuDatFileLoader - для загрузки каталогов из пакетов источников.
  • IcuResFileLoader - для загрузки каталогов из пакетов источников.
  • IniFileLoader - для загрузки каталогов из ini файлов.
  • MoFileLoader - для загрузки каталогов из gettext файлов.
  • PhpFileLoader - для загрузки каталогов из PHP файлов.
  • PoFileLoader - для загрузки каталогов из gettext файлов.
  • QtFileLoader - для загрузки каталогов из QT XML файлов.
  • XliffFileLoader - для загрузки каталогов из Xliff файлов.
  • JsonFileLoader - для загрузки каталогов из JSON файлов
  • YamlFileLoader - для загрузки каталогов из Yaml файлов (требует компонент Yaml).

Все загрузчики файлов требуют компонент Config.

Вы можете также создать ваш собственный загрузчик, в случае, если формат ещё не поддерживается ни одним из загрузчиков по умолчанию.

Вначале, вам нужно добавить один или более загрузчиков в Translator:

1
2
// ...
$translator->addLoader('array', new ArrayLoader());

Первый аргумент - это имя, на которое может ссылаться загрзучик в переводчике, а второй аргумент - экземпляр самого загрузчика. После этог, вы можете добавлять ваши источники, используя правильный загрузчик.

Загрузка сообщений с помощью ArrayLoader

Загрузка сообщений может производиться путём вызова addResource(). Первый аргумент - имя загрузчика (это был первый аргумент метода addLoader()), второй - источник, а третий - локаль:

1
2
3
4
// ...
$translator->addResource('array', array(
    'Hello World!' => 'Bonjour',
), 'fr_FR');

Загрузка сообщений с помощью загрузчиков файлов

Если вы используете один из загрузчиков файлов, вам нужно также использовать метод addResource(). Единственное различие - вам нужно использовать имя файла как второй аргумент файла источника, а не массива:

1
2
3
// ...
$translator->addLoader('yaml', new YamlFileLoader());
$translator->addResource('yaml', 'path/to/messages.fr.yaml', 'fr_FR');

Процесс перевода

Для того, чтобы на самом деле перевести сообщение, Переводчик использует простой процесс:

  • Каталог переведенных сообщений загружается из источника переводов, определённого для locale (например, fr_FR). Собщения из Компонент Translation также загружаются и добавляются в каталог, если они ещё не существуют. Конечный результат - большой "словарь" переводов;
  • Если сообщение расположено в каталоге, возвращается перевод. Если нет - переводчик возвращает исходное сообщение.

Вы начинаете этот процесс, вызывая trans() или transChoice(). Далее, Переводчик ищет точно такую же строку внутри соответствующего каталога сообщений и возвращает её (если она существует).

Резеврные локали

Если сообщения нет в каталоге определённой локали, переводчик будет искать в одном или нескольких каталогах резервных локалей. Например, представьте, что вы пытаетесь перевести на локаль fr_FR:

  1. Вначале переводчик ищет перевод в локали fr_FR;
  2. Если он не был найден, переводчик ищет перевод в локали fr;
  3. Если он всё равно не был найден, переводчик использует одну или несколько резервных локалей ясно установленных в переводчике.

Для (3), резервные локали можно установить, вызвав setFallbackLocales():

1
2
// ...
$translator->setFallbackLocales(array('en'));

Использования доменов сообщений

Как вы видели, файлы сообщений систематизируются в разные локали, которые они переводят. Файлы сообщений также могут быть организованы больше - в "домены".

Домен указывается в четвёртом аргументе метода addResource(). Домен по умолчанию - messages. Например, представьте, что в целях систематизации, переводы были разделены на три разных домена: messages, admin и navigation. Французский перевод будет загружаться так:

1
2
3
4
5
6
7
8
9
10
11
// ...
$translator->addLoader('xlf', new XliffFileLoader());

$translator->addResource('xlf', 'messages.fr.xlf', 'fr_FR');
$translator->addResource('xlf', 'admin.fr.xlf', 'fr_FR', 'admin');
$translator->addResource(
    'xlf',
    'navigation.fr.xlf',
    'fr_FR',
    'navigation'
);

При переводе строк, которые находятся не в домене по умолчанию (messages), вы должны указать домаен в качестве третьего аргумента trans():

1
$translator->trans('Symfony is great', array(), 'admin');

Symfony теперь будет искать сообщение в домене admin указанной локали.

Использование

Чтобы узнать, как использвать компонент Перевод, см. Использование Translator.

Узнать больше