Версия: 5.x
Интернационализация

Общие сведения

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

Все фразы, которые должны подлежать переводу необходимо обернуть специальной конструкцией:

В PHP файлах с помощью функции t():

//Рекомендуемый способ оборачивания текста с помощью функции t
echo t('Фраза на русском языке');
//Функция t() является синонимом \RS\Language\Core::translate()
echo \RS\Language\Core::translate('Фраза на русском языке');
//С подстановкой значений
echo t('Успешно выполнено %0 операций ', array('35')); //Вывод: Успешно выполнено 35 операций
echo t('Успешно выполнено %0 операций за %1 секунд ', array('35', '5')); //Вывод: Успешно выполнено 35 операций за 5 секунд
//С подстановкой значений и символьными идентификаторами
echo t('Успешно выполнено %key операций ', array('key' => '35')); //Вывод: Успешно выполнено 35 операций
echo t('Успешно выполнено %key операций за %time секунд', array('key' => '35', 'time' => '5')); //Вывод: Успешно выполнено 35 операций за 5 секунд
//С указанием идентификатора фразы. В языковом файле будет поиск не самой фразы, а идентификатора
echo t('Очень объемный текст с множеством переносов строк и.т.д. ', null, 'bigtext');
//С импользованием плагинов. Plural - плагин, который вставляет правильную форму существительного в зависимости от стоящего рядом числа
echo t('Артему %years [plural:%years:год|года|лет] ', array('years' => 1)); //Вывод: Артему 1 год
echo t('Артему %years [plural:%years:год|года|лет] ', array('years' => 2)); //Вывод: Артему 2 года
echo t('Артему %years [plural:%years:год|года|лет] ', array('years' => 5)); //Вывод: Артему 5 лет
//Перевод частовстречающегося слова в каком-то необычном контексте
//Фраза после символа ^ не отображается, однако в языковом файле ищется полный текст фразы для перевода
echo t('открыть^my_module_context'); //Вывод: открыть

В шаблонах Smarty с помощью блока t:

{t}Фраза на русском языке{/t}
{t key="35"}Успешно выполнено %key операций{/t}
{t key="35" time="5"}Успешно выполнено %key операций за %time{/t}
{t alias="bigtext"}Очень объемный текст с множеством переносов строк и.т.д.{/t}
{t years="1"}Артему %years [plural:%years:год|года|лет]{/t}
{t years="2"}Артему %years [plural:%years:год|года|лет]{/t}
{t years="5"}Артему %years [plural:%years:год|года|лет]{/t}
{t}открыть^my_module_context{/t}

В JavaScript файлах с помощью функции lang.t():

console.log(
lang.t('Фраза на русском языке'),
lang.t('Успешно выполнено %key операций ', {'key':'35'}), //Вывод: Успешно выполнено 35 операций
lang.t('Успешно выполнено %key операций за %time ',{'key':'35', 'time':'5'}), //Вывод: Успешно выполнено 35 операций за 5 секунд
lang.t('Очень объемный текст с множеством переносов строк и.т.д. ', null, 'bigtext'),
lang.t('Артему %years [plural:%years:год|года|лет] ', {'years':1}),
lang.t('Артему %years [plural:%years:год|года|лет] ', {'years':2}),
lang.t('Артему %years [plural:%years:год|года|лет] ', {'years':5}),
lang.t('открыть^my_module_context')
);

Наличие полных фраз в коде значительно улучшает его читаемость, однако это не очень удобно, когда переводу подлежат объемные тексты. Для этого можно устанавливать короткие идентификаторы фраз.

Учитывая то, что из всех языковых файлов формируется общий банк фраз, разные модули могут перекрывать своим переводом частоупотребляемые фразы. Для решения этой проблемы было введено понятие Контекст. Контекстом является та часть фразы, которая начинается с символа ^. Контекст не отображается в итоговой фразе, однако помогает придать ей уникальность в банке фраз.

Инициализация

Языковые функции инициализируются в классе RS::Config::AbstractSetup, путем вызова статического метода RS::Language::Core::init() и RS::Language::Core::initThemeLang(). В процессе инициализации происходит поиск и подключение языковых файлов в следующих папках:

  • /resource/lang/ИДЕНТИФИКАТОР_ЯЗЫКА/
  • /ИМЯ_МОДУЛЯ/view/lang/ИДЕНТИФИКАТОР_ЯЗЫКА/
  • /templates/ИМЯ_ТЕКУЩЕЙ_ТЕМЫ_ОФОРМЛЕНИЯ/resource/lang/ИДЕНТИФИКАТОР_ЯЗЫКА/

Идентификатором языка является двухсимвольное обозначение языка. Например: en,de,ru. Идентификатор языка получается с помощью метода RS::Language::getCurrentLang. Метод возвращает текущий язык системы по следующему правилу:

Если это административная зона:

  • попытка использовать язык, установленный в cookie
  • попытка использовать язык браузера
  • возвращается базовый язык

Если это клиентская часть:

  • попытка использовать язык, установленный в cookie
  • попытка использовать язык текущего сайта
  • возвращается базовый язык

Поиск языковых файлов в папке текущей темы оформления происходит только если пользователь находится в клиентской части сайта.

Формат языковых файлов

В перечисленных выше каталогах ожидаются файлы с именами:

  • messages.lng.php - фразы для PHP-файлов и шаблонов
  • messages.js.php - фразы для JavaScript

Для обоих файлов существует общий формат. Это должен быть обычный php файл, возвращающий массив фраз.

Пример языкового файла RU → EN:

<?
return array(
'Фраза на русском языке' => 'Phrase in English',
'Успешно выполнено %0 операций' => '%0 successfully completed transactions',
'Успешно выполнено %0 операций за %1 секунд' => '%0 successfully completed transactions in %1 second',
'Успешно выполнено %key операций' => '%key successfully completed transactions',
'Успешно выполнено %key операций за %time секунд' => '%key successfully completed transactions in %time second',
'bigtext' => 'Very very big text',
'Артему %years [plural:%years:год|года|лет]' => 'Artem %years [plural:%years:year|years]',
'открыть' => 'open',
'открыть^my_module_context' => 'OOOOOPEN'
);

Из фраз, указанных во всех файлах messages.js.php для текущего языка формируется файл /cache/lang/ИДЕНТИФИКАТОР_ЯЗЫКА.js, который подключается далее на всех страницах магазина.

Заметки
Языковые фразы кэшируются, поэтому при изменении или добавлении фраз для перевода необходимо очистить кэш. Или предварительно можно отключить кэширование в разделе Управление → Настройки системы.