Railsアプリをローカライズする

ロケールをルートとするRailsのYAMLを翻訳し、メッセージの検索、変数展開、複数形、リクエスト時のロケール選択を検証します。

Railsでは、tとI18n.tを通じてメッセージに固定の名前を付けられます。Lingo.devは、その名前に対応するYAMLを翻訳し、メッセージの検索、変数展開、ロケール選択は引き続きRailsが処理します。まずは挨拶と通知件数から始め、アプリケーションで実際に使っているヘルパーで確認しましょう。

翻訳元のメッセージをRailsのロケールファイルに配置する #

config/locales/en.ymlを作成するか、既存のファイルに追記します。

yaml
en:
  home:
    index:
      welcome: "Welcome, %{name}!"
      cta: "Create an account"
  notifications:
    unread:
      one: "One unread notification"
      other: "%{count} unread notifications"

app/views/home/index.html.erbでは、ビューを基準にした相対検索で挨拶を取得できます。

erb
<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>

ビューのパスにより、.welcomeの完全なキーはhome.index.welcomeになります。nameとcountは呼び出し元から渡されるため、翻訳でもこれらの変数名を保持する必要があります。oneやotherなどの複数形キーは分岐を識別するためのものなので、変更しないでください。

対応範囲を広げる際は、ビューに直接記述された残りのラベル、メールの文面、モデルのエラーメッセージを、適切なロケールの名前空間に移してください。ファイルを翻訳しても、反映されるのは、そのファイルのメッセージを読み込む呼び出し元だけです。

ロケールをルートとするYAMLを選択する #

RailsはYAMLのルートからロケールを読み取ります。en.ymlをes.ymlに変更しても、en:がそのままなら、定義されるメッセージは英語のままです。yaml-root-keyハンドラーを使い、値の翻訳とルート名の変更をまとめて行いましょう。

プロジェクトのルートでCLIをインストールし、連携を設定します。

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'config/locales/en.yml' --yes
lingo link

.lingo/config.jsonに書き込まれた組織とローカライゼーションエンジンのIDは、そのまま保持してください。同じファイルのfiles配列に、プロジェクトで使う翻訳元のエントリーを設定します。

json
[
  { "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
  { "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
]

2つ目のエントリーは、翻訳済みの同階層ファイルを対象に含めず、mailers.en.ymlのように関心事ごとに分けたファイルを対象にします。該当するファイルがなければ、このエントリーは削除してください。形式は明示的に指定します。汎用のYAML形式ではすべてのルートが保持されますが、CLIでYAMLソースを検出するには、形式を明示的に選ぶ必要があります。単一ルートのマッピング要件と再構築の動作については、ロケールをルートとするYAMLを参照してください。

翻訳し、読み込まれた値を確認する #

翻訳先ファイルがまだない場合は、次を実行します。

sh
lingo push --backfill-missing --wait

実行が完了したらconfig/locales/es.ymlを開き、ルートがes:になっていることを確認します。入れ子になったキーと変数名が翻訳元と一致しているか確認してください。シリアライズ後のコメント、アンカー、エイリアスも確認します。翻訳元の構成によっては、翻訳先パスの明示的な指定が必要です。

ロケールを明示的に選択し、Railsコンソールまたはアプリケーションのテストで結果を読み込みます。

ruby
I18n.with_locale(:es) do
  puts I18n.t("home.index.welcome", name: "Alex", raise: true)
  [0, 1, 2, 20].each do |count|
    puts I18n.t("notifications.unread", count: count, raise: true)
  end
end

この確認の前に、:en、:es、:frを利用可能なロケールとして設定してください。この例では、メッセージの検索と変数展開を検証します。意図した挨拶や通知件数を伝える文面になっているかも確認しましょう。翻訳先の言語によっては、翻訳元の英語にはない複数形のルールや分岐が必要です。フランス語でも同じ確認を行い、アプリケーションにメール送信やバリデーションの名前空間を追加した際は、それらも確認してください。

リクエストでも同じロケールが選ばれるようにする #

Railsの設定で、対応するロケールと既定のロケールを宣言します。対応ロケールの中から選んだ値を使ってリクエスト処理をI18n.with_localeで囲み、ロケールの状態が別のリクエストに引き継がれないようにします。

/esのようなURLでは、params[:locale]を読み取るコントローラーに加え、ルートのスコープも設定してください。生成するリンクにもロケールを保持します。アプリケーションがAccept-Languageによるロケールの選択にも対応している場合は、単に2文字を切り出すのではなく、優先度を表す重みと地域タグを解析してください。ユーザーが明示的にロケールを選べる場合は、その選択を優先します。

フォールバックの動作は、意図を明確にして選んでください。フォールバックはページを利用可能な状態に保つ一方で、スペイン語のメッセージの欠落を見えなくすることもあります。必須の翻訳先エントリーは、フォールバックに頼らず確認しましょう。日付と時刻のローカライズには、整形済みの日付をテキストとして翻訳するのではなく、必要に応じてRailsのlヘルパーを使ってください。

翻訳先言語のページを、直接アクセスとナビゲーション経由の両方で開いてください。Railsが翻訳先の名前空間を選択し、変数展開後の値を想定どおりに表示し、長くなったテキストも適切に扱えることを確認します。lingo checkはRailsのYAMLの網羅性を確認するものではありません。受け入れ確認には、引き続きRailsでの読み込み、描画、言語のレビューを含めてください。

翻訳元の変更に合わせて翻訳を保守する #

翻訳元ファイル、採用済みの翻訳先ファイル、設定、.lingo/lock.jsonはまとめて管理してください。メッセージを変更したら、通常の差分処理としてlingo push --waitを実行し、変更されたメッセージを隣接する未変更のメッセージと比較します。翻訳元の文面を変えずに翻訳を狙いどおりに修正するには、翻訳先を直接編集してください。YAMLキーのスコープでは、既存の翻訳が再利用されることがあります。翻訳指針の変更後に再生成する場合は、翻訳スコープの説明に従い、対象を絞ってファイル全体を置き換える前に、採用済みの翻訳を保存してください。

ローカルで修正した翻訳を、生成結果との相違による上書きから保護する必要がある場合は、--waitを付けずに送信し、lingo pull --dry-runを確認してから、送信に使ったチェックアウトで結果を取得してください。完了を待って書き戻す方式では、取得時点の最新状態に対する競合確認が行われません。他のチェックアウトには、バージョン管理を通じてコミット済みの翻訳が反映されます。レビュー済みの翻訳を保持するを参照してください。

ローカルで一連の作業ができるようになったら、GitHub AppまたはCIによる自動化を選びます。翻訳の差分をマージする前に、生成されたリソースに対して同じRailsの確認を実行してください。