JSON
パスごとにコピー、保持、除外、更新を指定しながら、入れ子の文字列値を翻訳します。
JSONカタログでは、アプリケーションがキーを検索し、その値を表示します。jsonファイルハンドラーは、オブジェクトのキー、配列内の位置、数値、真偽値、ヌル値をデータとして保持し、文字列値を変更します。現在のソースを基にターゲットを再構築し、新しい翻訳や、保持するターゲットのテキストを組み込みます。
このハンドラーは、入れ子のオブジェクトや配列で構成されたカタログに加え、ルートが文字列の場合にも対応しています。CLIは.jsonからjsonを推定します。ソースはCLI設定またはGitHub Appで設定します。
翻訳タスクの対象になるもの #
例:
{
"checkout": {
"title": "Complete your order",
"delivery": "Delivery within {days} days"
},
"plans": [
{ "name": "Personal", "seats": 1 },
{ "name": "Team", "seats": 10 }
],
"enabled": true
}ハンドラーはcheckout.title、checkout.delivery、plans[0].name、plans[1].nameを選択します。seatsの数値とenabledの真偽値は変更しません。文字列の識別子は、明示的に保護してください。値のJSON型からハンドラーが判断できるのは、それがテキストであることだけです。人が読むための内容かどうかまでは判断できません。
パスの短縮形式では、オブジェクトの階層をたどるにはドットを、配列内の位置を指定するには角かっこを使います。checkout.titleは入れ子の値を、plans[0].nameは最初のプランの名前を選択します。キー名が文字どおりcheckout.titleの場合は、引用符付きのJSONPath形式$['checkout.title']を使います。選択構文については、キーの制御を参照してください。
更新時に既存の翻訳を再利用する仕組み #
差分実行では、次の3種類の入力を使います。
| 入力 | ロール |
|---|---|
| 現在のソース | 新しい出力の構造と文字列を定義します。 |
| 前回のソース | 同じパスにあるソース文字列が変更されたかどうかを判定する基準になります。 |
| 既存のターゲット | 保持できる翻訳の取得元になります。 |
前回のソースと既存のターゲットが利用できる場合、新規または変更されたソース文字列が翻訳タスクになります。変更のないソース文字列には、対応するパスにある既存のターゲット値を再利用できます。英語のテキストが同じでも、2つのキーは別々のレコードとして扱われます。文脈が異なれば、それぞれ異なる翻訳が採用されることがあります。
たとえば、checkout.titleを変更しただけで、checkout.deliveryの再翻訳が必要になるわけではありません。後者のソース値に変更がなく、ターゲット値が利用できる場合は、その値を引き継げます。新たに翻訳する文字列がなくても、数値などの構造に関わるデータが変わると、ファイルの再構築が必要になる場合があります。
前回のソースは、採用済みのターゲットと対にして保持してください。どちらかが欠けている場合、ハンドラーは文字列を初回の処理として扱います。CLIのLockfileとキャッシュが、実行をまたいでこれらの入力を結び付けます。
保護するパスの処理方法を選ぶ #
これらの制御では、出力の扱いがそれぞれ異なります。
| 制御 | 翻訳時の動作 | 出力時の動作 |
|---|---|---|
| ロックするパス | 翻訳対象から除外します。 | 現在のソースの値を使います。 |
| 保持するパス | 翻訳対象から除外します。 | 既存のターゲットにそのパスがあれば値を保持し、なければソースの値を残します。 |
| 無視するパス | 翻訳対象から除外します。 | 生成するターゲットからそのパスを削除します。 |
| ロケールの挿入 | 設定されたロケールフィールドを翻訳対象から除外します。 | そのフィールドにターゲットロケールを書き込みます。 |
すべてのロケールでソースの値を使う必要がある共有識別子は、ロックします。ロケールごとにリンク先を管理するターゲット固有のアドレスは、保持します。翻訳後のファイルに含めてはいけないソース専用のメモは、無視します。これらは、単に「翻訳しない」ことを表す同義の選択肢ではありません。
同じパスではロックが保持より優先されるため、両方のリストに含まれる値にはソースの値が使われます。無視を指定すると、ロック、保持、ロケール挿入の対象であっても、その値は削除されます。ロケールの挿入先では、挿入がロックと保持より優先されます。各値を管理する制御は1つに絞ることをおすすめします。オブジェクトや配列にまたがってルールが重なる場合は、出力を確認してください。
配列の要素を削除すると、後続の要素の位置がずれます。生成された配列は、翻訳テキストとしてだけでなく、データとしてもレビューしてください。ロケールの挿入では、格納先のオブジェクトがなければ作成できます。配列に書き込む場合は、既存の要素か、末尾のすぐ次の位置を指定してください。途中に空きを作るパスや、互換性のない値を経由するパスへの書き込みは失敗します。
これらの制御は、CLIのファイルエントリーフィールドまたはGitHubのファイルエントリーオプションで設定します。
処理範囲と再構築の制限 #
キーの更新では、選択した翻訳を既存のターゲットに統合します。選択されていないターゲット値や、ターゲットにのみ存在するキーはそのまま残り、省略された項目も省略されたままになります。処理範囲外にあるソース専用のキーは追加されません。配列への書き込みでは、途中に空きを作ることはできません。たとえば、配列の2番目の要素を選択しても、存在しない最初の要素が自動で補われることはありません。部分更新の後は、ターゲット全体を確認してください。
JSON出力は、スペース2個分のインデントと末尾の改行を付けてシリアライズされます。空白やコメントがバイト単位でそのまま保持されることは想定しないでください。コメントを含むソースファイルについてはJSONCを参照してください。また、書き換え後のファイルを元のファイルと同等と見なす前に、そのファイルを利用するシステムの要件を確認してください。
翻訳ワークフローでは、対応するプレースホルダーとICUの構造を検証し、引数の変更や欠落も確認します。報告された警告や失敗を確認してから、採用済みのテンプレートにアプリケーションの値を適用して表示してください。これらの検証では、翻訳されたメッセージが意図した意味を伝えているかどうかまでは評価しません。
代表的な値を使って、出力をアプリケーションに読み込んでください。保護したパスに意図したソースまたはターゲットのデータが保持されていることと、値を置換した後も、配信に関するメッセージが同じ約束を伝えていることを確認してください。構文解析で検証できるのはJSONの構文です。実際に表示して読むことで、利用者に届くメッセージを検証できます。