Компонент Translation
Дата обновления перевода 2023-06-30
Компонент 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
:
- Вначале переводчик ищет перевод в локали
fr_FR
; - Если он не был найден, переводчик ищет перевод в локали
fr
; - Если он всё равно не был найден, переводчик использует одну или несколько резервных локалей ясно установленных в переводчике.
Для (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.