Переводы

Магазин на Magento часто работает на нескольких языках. Поэтому строки в коде не выводят напрямую: их оборачивают в функцию __(), а перевод хранят в отдельном файле. Исходные строки принято писать по-английски — они служат ключами. В предыдущих уроках русские строки стояли в коде только для наглядности.

Где лежат переводы

Переводы модуля находятся в папке i18n, по одному файлу CSV на язык. Имя файла — код языка и страны: ru_RU.csv, de_DE.csv. Файл создают вручную.

app/code/Acme/Hello/
├── i18n/
│   └── ru_RU.csv           новый файл
└── view/frontend/templates/greeting.phtml

Переводимая строка

<!-- app/code/Acme/Hello/view/frontend/templates/greeting.phtml -->
<h2><?= $escaper->escapeHtml(__('Hello!')) ?></h2>

Функция __() ищет перевод строки для языка текущей витрины. Если перевода нет, выводится исходная строка — «Hello!».

Файл перевода

"Hello!","Здравствуйте!"
"Welcome to %1!","Добро пожаловать в %1!"
"Reviews","Отзывы"

Это содержимое файла app/code/Acme/Hello/i18n/ru_RU.csv. В каждой строке две части в кавычках через запятую: исходная фраза и перевод. Исходная фраза должна совпадать с аргументом __() до последнего символа.

Включение языка

Язык витрины выбирают в панели: «Магазины → Конфигурация → Общие → Общие → Региональные настройки» (Stores → Configuration → General → General → Locale Options), поле Locale. Значение можно задать отдельно для каждой витрины.

bin/magento cache:clean

После сброса кеша страница /hello на русской витрине покажет «Здравствуйте!», а на английской — «Hello!».

Подстановка значений

Изменяемые части фразы обозначают метками %1, %2 и передают следующими аргументами:

// app/code/Acme/Hello/Model/Greeter.php
public function greet(string $name): string
{
    return (string) __('Hello, %1!', $name);
}

В файле перевода метки можно переставить: "Hello, %1!","%1, здравствуйте!". Функция возвращает не строку, а объект фразы — он превращается в текст при выводе или приведении к string.

Строки в XML

Подписи из файлов XML тоже переводятся — их добавляют в тот же файл CSV:

Строки в JavaScript

В скриптах используют функцию $t() из модуля mage/translate: $t('Hello!'). Переводы для неё Magento собирает в отдельный файл вместе со стилями и скриптами, поэтому после изменения перевода статические файлы нужно пересобрать.

Сбор фраз

Чтобы не выписывать фразы вручную, их собирает команда:

bin/magento i18n:collect-phrases -o app/code/Acme/Hello/i18n/en_US.csv app/code/Acme/Hello

Она просматривает код модуля и создаёт файл, где каждая фраза повторена дважды. Скопируйте его под именем ru_RU.csv и замените вторую половину строк переводом.

Откуда берётся перевод

Готовые переводы ядра на многие языки устанавливают языковыми пакетами.

Частая ошибка

В __() передают переменную или склеенную строку: __('Hello, ' . $name) или __($message). Команда сбора фраз такую строку не найдёт, а перевод для каждого имени составить невозможно. В __() всегда пишите постоянную строку целиком, а изменяемые части подставляйте метками %1.