CyberTrain指南国际化

国际化

与 Rails 同样形式的翻译文本:config/locales/*.yml 中的词典,模板、控制器和模型中的 t 与 l,每个请求各自的语言区域(locale),以及为验证消息、日期、数字和认证页面捆绑的英语和日语词典。

词典

词典是 config/locales/(包括子目录)下的 YAML 文件,其第一个键是语言区域: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 读取 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,返回当前语言区域中某个键的文本:

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}:为 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 值保持原样)。其他文本都会被转义。

erb
<%= 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:

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) 按 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 时就是捆绑的英语)。