YAML
カタログのキーを変えずに、入れ子になった YAML の文字列値を翻訳します。ルートやスキーマに特別な意味がある場合は、別のハンドラーを選んでください。
yaml ファイルハンドラーは、入れ子になったマッピングやシーケンス内の文字列値を翻訳します。アプリケーションのコードが検索に使うキーや、数値、真偽値はそのまま保持します。ロケール間で構造が変わらないカタログに使用してください。
汎用 YAML が適しているかを判断する #
たとえば、次のカタログは、ロケールのラッパーを使わずに購入手続きのメッセージをまとめたものです。
checkout:
title: Complete your order
steps:
- Review your items
- Confirm delivery
retries: 3ハンドラーは checkout.title と、シーケンス内の両方の文字列を選択します。retries は数値のまま保持されます。引用符で囲まれた識別子も、文字列なので選択されます。カタログに含めるデータを決める際は、この違いに注意してください。
Rails 形式の en: ラッパーを翻訳先のロケールに変更する必要がある場合は、ロケールをルートとする YAML を使用してください。汎用 YAML では、ファイル名が es.yml に変わっても en: は保持されます。その結果、ルートが英語を指定したままになるため、Rails が内容を無視することがあります。
API 仕様には OpenAPI を使用してください。汎用 YAML では、文字列値を持つ操作識別子や参照、例も選択されます。.yml という拡張子だけでは、こうした用途の違いを区別できません。
再利用と再構築 #
出力ツリーの構造は、現在のソースによって決まります。以前のソースを基準に、各パスの文字列に変更があったかを判定し、一致するパスにある既存の翻訳先の値を利用します。変更された文字列は新しい翻訳に置き換えられます。変更のない文字列は、キーや用語で指定した対象範囲に含まれていても、既存の翻訳を保持できます。
CLI は --key に保存済みの基準データを渡すため、この方法で対象を選択しても、変更のない YAML の文言が必ず再生成されるとは限りません。同じコマンドに --force を追加しても、この動作は変わりません。意図どおりに修正するには、翻訳先を直接編集してください。再生成する場合は、承認済みの翻訳先を保存したうえで、--key を付けずに、対象範囲を指定してファイル全体に --force を実行してください。置き換え後は、ファイル全体をレビューしてください。
再構築では YAML の構文木を使い、コメントやアンカーの構造を保持しながら値を置き換えます。シリアライズ時に書式が正規化されることがあります。コメントは文書の一部として保持され、翻訳者への指示としては扱われません。特に、複数の参照から同じ値を使っている場合は、YAML を読み込む側でエイリアスの動作を確認してください。
キーで対象範囲を指定して実行すると、翻訳先の値が存在しない場合に、対象範囲外のマッピング内にある未解決の文字列が削除されることがあります。シーケンス内の文字列は、位置がずれないようにソースの値を保持します。そのため、一部の範囲を処理しただけでは、ファイル内のすべての文字列が翻訳済みとは限りません。
カタログを設定して読み込む #
.yaml または .yml のソースには、CLI 設定で format: "yaml" を明示的に設定してください。プッシュ時のファイル検出では、形式が明示されていない YAML ファイルは除外されます。GitHub App では、リポジトリの選択を別途行います。
翻訳先のパスは、アプリケーションのローダーに合わせてください。config/locales/checkout.en.yml のようなソースと locales/en/checkout.yml にあるソースでは、パスの導出方法が異なります。シーケンス内の位置もメッセージの識別に使われるため、項目を移動すると、対応する既存の翻訳が変わることがあります。構造を編集した後は、読み込まれたカタログを確認してください。Rails での検索、ロケールの選択、フォールバックについては、Rails アプリをローカライズするを参照し、ロケールをルートとするハンドラーを使用してください。