词典
词典是 config/locales/(包括子目录)下的 YAML 文件,其第一个键是语言区域: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 读取 config/locales/ 下的每个 *.yml,并把它们编译进 gen/locales.rb,因此程序自带文本,运行时不读取 YAML;词典改变时开发服务器会重新生成它,spin run gen -- --check 会报告它已过时。文件按路径顺序读取,后一个文件中的键会替换前一个文件中的同名键。若某个键在一个文件中是映射、在另一个文件中是文本或列表,gen 会停下,并指出两个文件及其行号。
gen 读取的 YAML
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}:为 0 且键有 zero 时用它,否则用语言区域的类别,再否则用 other。
| 语言 | 类别 |
|---|---|
| 英语,以及表中未列出的所有语言 | 1 为 one,其余为 other |
| 法语 | 0 和 1 为 one,非零的 1,000,000 的倍数为 many,其余为 other |
| 俄语 | one(1、21、101),few(2 到 4、22 到 24),其余为 many |
| 日语、中文 | other |
带地区的语言区域使用其语言的规则(pt-BR 用 pt 的)。count_text: 用一个 String 填入 %{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 |
在控制器中,Admin::PostsController#create 里的 t(".created") 读取 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.formats 或 date.formats 格式化 Time 或 Date:
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)按 q 值、再按顺序读取Accept-Language,先匹配完整标签再匹配其语言(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 上的消息单独出现。属性名是 gen 为每个模型写出的 Post.human_attribute_name(:title):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,而不会输出缺少分隔符的数字。从 Ruby 调用的Cybertrain::NumberHelper保持英语默认值。 - 带格式名、或不带
format:的time_tag经过l;模式 String 保留 strftime 的英语名称。 time_ago_in_words和distance_of_time_in_words读取datetime.distance_in_words("2分")。pluralize只在语言区域为英语时使用英语的词形变化;其他情况下,除非给出复数形式,词保持不变。paginate的链接、作业页面以及没有模型的提交按钮读取cybertrain.*键,应用可以像其他键一样覆盖它们。
缺失的键
在当前语言区域和默认语言区域中都找不到的键会返回:
| 位置 | 生产以外(开发、测试、预发布) | 生产 |
|---|---|---|
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 时就是捆绑的英语)。