CyberTrainガイド国際化

国際化

Rails と同じ形の翻訳テキストです:config/locales/*.yml の辞書、テンプレート・コントローラー・モデルからの t と l、リクエストごとのロケール、そしてバリデーションメッセージ・日付・数値・認証画面のための英語と日本語の辞書の同梱です。

辞書

辞書は 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 を読みます。辞書が使うものを受け付け、それ以外はファイルと行を示して拒否します:

  • 受け付けるもの:入れ子のマッピング、1 行に収まるプレーン・'シングル'・"ダブル" クォートの値(\n、\t、\"、\\、\uXXXX)、| と > のブロック、値のリスト(ブロックの要素として。rails-i18n の書き方どおりキーと同じインデントでもよい。または [a, b])、コメント、先頭の ---、BOM と CRLF の改行、空のテキストとしての ~、null、何も書かないこと。
  • 値はすべてテキストのまま保たれます:3 は "3"、no は "no"、:year は ":year" です。
  • 拒否するもの:アンカーとエイリアス、タグ、2 つ目のドキュメント、{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、0 でない 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 や 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= パラメーター(以後クッキーに保存)、なければクッキー、なければブラウザーの 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 のメッセージは単独で出します。属性の名前は 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 は残ります。サインインページのタイトルを変えたり、画面を 3 つ目の言語に翻訳したりするには、それらのキーを config/locales/ に書きます。同梱の辞書がないロケールでは、アプリケーションにないキーはデフォルトのロケールのテキスト(デフォルトが en なら同梱の英語)にフォールバックします。