Компонент Перевод

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

Установка

Вы можете установить компонент 2 разными способами:

Then, require the vendor/autoload.php file to enable the autoloading mechanism provided by Composer. Otherwise, your application won't be able to find the classes of this Symfony component.

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

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

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

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

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

$translator = new Translator('fr_FR', new MessageSelector());

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.yml', 'fr_FR');

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

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

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

Вы начинаете этот процесс, вызывая 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 указанной локали.

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

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

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.