Как локализовать приложение на Rails
Переведите YAML-файлы Rails с локалью в корне и проверьте поиск переводов, подстановку значений, формы множественного числа и выбор локали для запроса.
Rails уже задаёт сообщениям постоянные имена с помощью t и I18n.t. Lingo.dev может перевести YAML с этими сообщениями, а Rails по-прежнему будет отвечать за поиск переводов, подстановку значений и выбор локали. Начните с приветствия и количества уведомлений, затем проверьте их теми же вспомогательными методами, которые использует приложение.
Добавьте исходные сообщения в файл локали Rails #
Создайте или дополните config/locales/en.yml:
en:
home:
index:
welcome: "Welcome, %{name}!"
cta: "Create an account"
notifications:
unread:
one: "One unread notification"
other: "%{count} unread notifications"В app/views/home/index.html.erb для приветствия можно использовать поиск относительно представления:
<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>Путь к представлению задаёт для .welcome полный ключ home.index.welcome. Вызывающий код передаёт name и count — в переводе эти имена подстановок должны сохраниться. Ключи форм множественного числа, например one и other, обозначают ветви и остаются без изменений.
По мере расширения локализации переносите оставшиеся подписи в представлениях, тексты писем и сообщения об ошибках моделей из кода в соответствующие пространства имён локалей. Перевод файла влияет только на код, который загружает из него сообщения.
Выберите YAML с локалью в корне #
Rails считывает локаль из корневого ключа YAML. Если переименовать en.yml в es.yml, но оставить en:, сообщения по-прежнему будут определены как английские. Используйте обработчик yaml-root-key, чтобы одновременно перевести значения и переименовать корневой ключ.
Установите и привяжите CLI из корня проекта:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'config/locales/en.yml' --yes
lingo linkОставьте идентификаторы организации и движка локализации, записанные в .lingo/config.json. В массиве files укажите записи для исходных файлов проекта:
[
{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
{ "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
]Вторая запись охватывает файлы для отдельных частей приложения, например mailers.en.yml, но не выбирает соседние файлы с переводами. Удалите её, если таких файлов в проекте нет. Укажите формат явно: обычный YAML сохраняет все корневые ключи, а автоматическое обнаружение в CLI требует явно выбрать формат для исходных YAML-файлов. В разделе YAML с локалью в корне описаны требование к структуре с одним корневым ключом и то, как восстанавливается файл.
Переведите и проверьте загруженные значения #
Если целевых файлов ещё нет, выполните:
lingo push --backfill-missing --waitПосле завершения откройте config/locales/es.yml и убедитесь, что корневой ключ — es:. Сверьте вложенные ключи и имена подстановок с оригиналом. Проверьте комментарии, якоря и псевдонимы после сериализации. Если структура исходных файлов отличается, может понадобиться явно указать целевой путь.
Загрузите результат в консоли Rails или в тестах приложения, явно выбрав локаль:
I18n.with_locale(:es) do
puts I18n.t("home.index.welcome", name: "Alex", raise: true)
[0, 1, 2, 20].each do |count|
puts I18n.t("notifications.unread", count: count, raise: true)
end
endПеред проверкой добавьте :en, :es и :fr в список доступных локалей. Пример проверяет поиск переводов и подстановку значений. Прочитайте текст и убедитесь, что приветствие и количество уведомлений переданы верно. Для целевых языков могут понадобиться правила и ветви множественного числа, которых нет в английском оригинале. Повторите проверку для французского языка, а также для пространств имён писем и валидации по мере их добавления.
Настройте выбор той же локали для запросов #
Задайте поддерживаемые локали и локаль по умолчанию в конфигурации Rails. Оберните обработку запроса в I18n.with_locale, передав значение из списка поддерживаемых локалей, чтобы настройка локали не переносилась на другой запрос.
Для URL вида /es настройте и область маршрутов, и контроллер, который считывает params[:locale]. Сохраняйте локаль в создаваемых ссылках. Если приложение также выбирает язык по Accept-Language, разбирайте веса приоритета и региональные теги, а не просто берите подстроку из двух букв. Явный выбор пользователя должен иметь приоритет, если приложение его поддерживает.
Продумайте, как будут работать резервные переводы. Они могут сохранить работоспособность страницы, но скрыть отсутствие сообщения на испанском. Поэтому проверяйте обязательные записи на целевом языке, не полагаясь на резервные переводы. Для локализации даты и времени используйте вспомогательный метод Rails l, где это уместно, вместо перевода уже отформатированной даты как текста.
Откройте страницу на целевом языке напрямую и через навигацию. Убедитесь, что Rails выбирает целевое пространство имён, показывает ожидаемые значения подстановок и корректно отображает более длинный текст. lingo check не проверяет полноту YAML-файлов Rails. При приёмке по-прежнему проверяйте загрузку и отображение в Rails, а также качество языка.
Обновляйте переводы при дальнейших изменениях оригинала #
Храните исходные файлы, принятые переводы, конфигурацию и .lingo/lock.json вместе. После изменения сообщения запустите lingo push --wait для обычного перевода изменений и сравните изменённое сообщение с соседним неизменённым. Чтобы точечно исправить перевод при неизменном оригинале, отредактируйте целевой файл напрямую: при переводе YAML с областью видимости ключей может повторно использоваться существующий перевод. Чтобы заново создать перевод после изменения указаний, сохраните принятые переводы перед полной заменой файлов в выбранной области, как описано в разделе области перевода.
Если локальные исправления переводов нужно защитить от расхождений, отправьте задачу без --wait, проверьте lingo pull --dry-run и получите результат в том же checkout, из которого отправляли задачу. Запись результата в режиме ожидания не выполняет такую повторную проверку конфликтов. Другие checkout получают переводы из коммитов через систему контроля версий. См. Как сохранить проверенные переводы.
Когда локальный цикл заработает, выберите GitHub App или автоматизацию в CI. Перед слиянием изменений перевода выполните те же проверки Rails для созданных ресурсов.