CyberTrainРуководстваИнтернационализация

Интернационализация

Переводы в форме Rails: словари в config/locales/*.yml, t и l в шаблонах, контроллерах и моделях, своя локаль у каждого запроса и встроенные английский и японский словари для сообщений валидации, дат, чисел и экранов аутентификации.

Словари

Словарь — это YAML-файл в config/locales/ (включая подкаталоги), первый ключ которого — локаль: en, ja, pt-BR. cybertrain new записывает config/locales/en.yml; добавьте по файлу на язык и перечислите языки в config/app.rb.

config/locales/ja.yml (фрагмент, examples/blog)yaml
ja:
  activerecord:
    models:
      article: "記事"
    attributes:
      article:
        title: "タイトル"
        body: "本文"
  articles:
    index:
      title: "記事"
      count:
        other: "%{number}件の記事"
config/app.rbruby
Cybertrain.configure do |c|
  c.i18n_available_locales = [:en, :ja]
end

spin run gen читает все *.yml в config/locales/ и компилирует их в gen/locales.rb, так что программа несёт тексты в себе и не читает YAML при работе; сервер разработки пересоздаёт файл, когда меняется словарь, а spin run gen -- --check сообщает, что он устарел. Файлы читаются в порядке путей, и ключ из более позднего файла заменяет тот же ключ из более раннего. Ключ, который в одном файле — отображение, а в другом — текст или список, останавливает gen с указанием обоих файлов и строк.

YAML, который читает gen

gen читает YAML собственным читателем: он принимает то, чем пользуются словари, а остальное отвергает с указанием файла и строки:

  • Принимается: вложенные отображения; простые значения и значения в 'одинарных' и "двойных" кавычках на одной строке (\n, \t, \", \\, \uXXXX); блоки | и >; списки значений — элементами блока (в том числе на отступе своего ключа, как пишет rails-i18n) или [a, b]; комментарии, --- в начале, BOM и переводы строк CRLF; ~, null или ничего — пустой текст.
  • Каждое значение хранится как текст: 3 — это "3", no — "no", :year — ":year".
  • Отвергается: якоря и псевдонимы, теги, второй документ, отображения {a: b}, ключи в кавычках, повторяющийся ключ, табуляция в отступе, элемент списка, не являющийся значением, первый ключ, не являющийся именем локали, и простое значение или значение в кавычках, продолжающееся на следующей строке (запишите его через | или >).

Поиск текста

t в шаблоне, t в контроллере и I18n.t во всех остальных местах возвращают текст по ключу в текущей локали:

ruby
I18n.t("greeting", name: "Ann")            # "Hello, %{name}" => "Hello, Ann"
I18n.t("nope", default: "Nothing")         # String или Symbol с именем другого ключа
I18n.t("greeting", name: "Ann", locale: :ja)
I18n.translate_list("date.abbr_day_names") # => ["Sun", "Mon", ...]

Каждая опция, кроме default:, count:, count_text: и locale:, заполняет одноимённый %{name}; %% — это буквальный %, так что %%{x} даёт %{x}, а %{x} без значения вызывает I18n::MissingInterpolationArgument. Ключ, не найденный в текущей локали, ищется в локали по умолчанию. Списки, такие как названия дней и месяцев, берутся из I18n.translate_list, поскольку t всегда возвращает String.

Количества и формы множественного числа

count: (Integer) выбирает форму под ключом и заполняет %{count}: zero для 0, если она есть у ключа, иначе категорию локали, иначе other.

Язык Категории
Английский и любой язык, которого нет в таблице one для 1, иначе other
Французский one для 0 и 1, many для ненулевого кратного 1 000 000, иначе other
Русский one (1, 21, 101), few (от 2 до 4, от 22 до 24), иначе many
Японский, китайский other

Региональная локаль следует правилу своего языка (pt-BR — правилу pt). count_text: заполняет %{count} строкой, не выбирая форму, — так сообщения numericality передают свои границы.

Ленивый поиск

Ключ, начинающийся с ., относительный. В шаблоне он ищется по собственному пути шаблона, как в Rails:

Шаблон t(".title") читает
app/views/posts/index.html.erb posts.index.title
app/views/posts/new.html.erb, в том числе когда его рендерит create posts.new.title
app/views/posts/_form.html.erb posts.form.title
app/views/layouts/application.html.erb layouts.application.title
app/views/__components/card_component.html.erb card_component.title
app/views/mail/_password_reset.html.erb mail.password_reset.title

В контроллере t(".created") в Admin::PostsController#create читает admin.posts.create.created.

HTML в тексте

Ключ, оканчивающийся на _html (или .html), — это HTML: шаблон выводит его как есть и экранирует каждое подставленное значение (значение SafeString остаётся как есть). Любой другой текст экранируется.

erb
<%= t(".intro_html", name: @user.name) %>   <%# "Hello <b>%{name}</b>": the name is escaped, <b> is not %>

Даты и время

l в шаблоне и I18n.l форматируют Time или Date по time.formats или date.formats локали:

ruby
I18n.l(Time.utc(2026, 11, 10, 9, 5), format: :long)                  # => "November 10, 2026 09:05"
I18n.l(Date.new(2026, 11, 10), locale: :ja)                          # => "2026/11/10"
I18n.l(Time.utc(2026, 11, 10, 9, 5), format: "%a %p", locale: :ja)   # => "火 午前"

format: — это имя формата (:default, если не указано, :short, :long или любое другое, которое есть в словарях) или шаблон. %a %A %b %B берут из словаря названия дней и месяцев, а %p %P — его time.am / time.pm (и с ^, %^B); остальное — директивы strftime, форматируемые по одной, как в time_tag (неизвестная директива вызывает исключение). Директива названия с другим флагом или шириной (%-A, %10B, %#b) тоже принадлежит strftime и печатает английское название; форматы rails-i18n таких не используют. Имя формата, которого нет ни в одном словаре, вызывает I18n::MissingTranslationData. Time показывается в поясе приложения или, с zone: "America/New_York", в другом (Часовые пояса).

Выбор локали

Каждый запрос начинается с локали по умолчанию (config.i18n_default_locale, :en или CYBERTRAIN_I18N_DEFAULT_LOCALE). Приложение меняет её в before_action, как это делает examples/blog: параметр ?locale=, который затем сохраняется в cookie, иначе cookie, иначе Accept-Language браузера.

app/controllers/application_controller.rb (фрагмент, examples/blog)ruby
class ApplicationController < Cybertrain::Controller
  before_action :set_locale

  private

  def set_locale
    param = params[:locale]
    if I18n.locale_available?(param)
      I18n.locale = param
      cookies[:locale] = param.to_s
      return nil
    end

    stored = cookies[:locale]
    if I18n.locale_available?(stored)
      I18n.locale = stored
      return nil
    end

    I18n.locale = request.preferred_locale(I18n.available_locales)
    nil
  end
end
  • I18n.locale принадлежит потоку, который обслуживает запрос, так что запросы, обслуживаемые одновременно, сохраняют каждый свою; фреймворк возвращает её к значению по умолчанию перед каждым запросом и каждым действием, а также перед каждым заданием и каждой задачей планировщика, которые выполняет рабочий поток, так что задание, которое её устанавливает (уведомление на языке пользователя), оставляет следующее задание в этом потоке со значением по умолчанию. I18n.with_locale говорит то же самое в блоке.
  • I18n.locale = value принимает Symbol или String и только имя из config.i18n_available_locales (если список пуст — только локаль по умолчанию); любое другое вызывает I18n::InvalidLocale. Она сравнивает имена и никогда не превращает текст запроса в Symbol, так что параметр можно передать как есть, когда I18n.locale_available? ответил «да».
  • request.preferred_locale(available) читает Accept-Language по q-значению, затем по порядку, сопоставляет полный тег раньше его языка (ja-JP даёт :ja) и возвращает элемент available или локаль по умолчанию, если ничего не совпало.
  • I18n.with_locale(:ja) { ... } выполняет блок в другой локали и возвращает прежнюю, даже если блок вызвал исключение: например, письмо пользователю на его языке.

Письмо, собранное в запросе, или трансляция, отрисованная там же, получают локаль этого запроса.

Модели и сообщения валидации

Сообщение валидации ищется при запуске валидатора, в текущей локали, по ключам Rails: activerecord.errors.models.<model>.attributes.<attr>.<type>, activerecord.errors.models.<model>.<type>, activerecord.errors.messages.<type>, errors.attributes.<attr>.<type>, затем errors.messages.<type>, где лежат встроенные тексты. message: в строке валидации по-прежнему имеет приоритет. Текст может использовать %{attribute}, %{model}, %{count} и, как в Rails, %{value} — значение атрибута ("%{value} is already taken").

errors.full_messages соединяет имя атрибута и сообщение по errors.format ("%{attribute} %{message}"; японский пишет без пробела), а сообщение на :base стоит отдельно. Имя атрибута — это Post.human_attribute_name(:title), который gen пишет для каждой модели: activerecord.attributes.post.title, иначе атрибут в читаемом виде (author_id даёт "Author"). I18n.human_model_name("post") читает activerecord.models.post (его форму one:, если есть формы множественного числа), иначе последний сегмент ключа в читаемом виде ("admin/post" даёт "Post"). Post.model_name.human нет.

Конструктор форм читает те же имена: f.label :title — это helpers.label.<область формы>.title, иначе human_attribute_name, а f.submit — helpers.submit.create или update с именем модели (по-английски "Create Article"; японский у rails-i18n — "登録する", без имени).

Хелперы, которые следуют локали

  • Числовые хелперы в шаблоне читают number.* локали: разделители, единицу и формат number_to_currency (по-японски "1,234円") и единицы number_to_human и number_to_human_size. Опция, переданная в вызове, имеет приоритет. Настройка, которой нет ни в текущей локали, ни в локали по умолчанию, берётся английской, как хелперы Rails возвращаются к своим значениям по умолчанию: приложение, у локали по умолчанию которого нет ключей number.*, всё равно печатает 1,234.5 и $12.50, а не число без разделителей. Cybertrain::NumberHelper, вызванный из Ruby, сохраняет английские значения по умолчанию.
  • time_tag с именем формата или без format: проходит через l; строка-шаблон сохраняет английские названия strftime.
  • time_ago_in_words и distance_of_time_in_words читают datetime.distance_in_words ("2分").
  • pluralize использует английский инфлектор, только когда локаль английская; в остальных случаях слово остаётся как есть, если не передана форма множественного числа.
  • Ссылки paginate, страница заданий и кнопка отправки без модели читают ключи cybertrain.*, которые приложение может переопределить, как и любые другие.

Отсутствующие ключи

Ключ, которого нет ни в текущей локали, ни в локали по умолчанию, даёт:

Где Вне продакшена (разработка, тесты, staging) Продакшен
I18n.t, t контроллера "translation missing: ja.foo.bar" "Bar", последний сегмент в читаемом виде
t шаблона <span class="translation_missing" title="translation missing: ja.foo.bar">Bar</span> Bar

config.i18n_raise_on_missing = true вместо этого везде вызывает I18n::MissingTranslationData; default: по-прежнему срабатывает первым. examples/blog включает это в своих тестах (c.i18n_raise_on_missing = true if c.test?), так что ключ, которого нет в обоих словарях, проваливает тест, а не выводит метку.

Встроенные словари

Фреймворк поставляется с английским и японским словарями (cybertrain/locales/en.yml и ja.yml): ключи rails-i18n для того, чем пользуется фреймворк (сообщения валидации, date, time, datetime.distance_in_words, number, helpers.submit, errors.template), собственные ключи фреймворка под cybertrain. и все тексты экранов, которые пишет cybertrain generate authentication (sessions.new.title, passwords.create.sent, ключи писем, activerecord.attributes.user).

Ключ приложения переопределяет встроенный ключ с тем же именем в этой локали. Формы множественного числа объединяются: приложение, которое пишет только datetime.distance_in_words.x_days.zero: "today", сохраняет встроенные one и other. Чтобы изменить заголовок страницы входа или перевести экраны на третий язык, запишите их ключи в config/locales/. В локали без встроенного словаря ключ, которого нет у приложения, берётся из текста локали по умолчанию (встроенного английского, если по умолчанию en).