Словари
Словарь — это YAML-файл в config/locales/ (включая подкаталоги), первый ключ которого — локаль: en, ja, pt-BR. cybertrain new записывает config/locales/en.yml; добавьте по файлу на язык и перечислите языки в config/app.rb.
ja:
activerecord:
models:
article: "記事"
attributes:
article:
title: "タイトル"
body: "本文"
articles:
index:
title: "記事"
count:
other: "%{number}件の記事"
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 во всех остальных местах возвращают текст по ключу в текущей локали:
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 остаётся как есть). Любой другой текст экранируется.
<%= 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 локали:
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 браузера.
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).