キー制御
値の取得元を、ソースコンテンツ、既存の翻訳先コンテンツ、翻訳、ロケールのメタデータから選択します。
カタログの値には、どの言語でも同じ値に保つものもあれば、人が管理する翻訳先の値を使うものもあります。キー制御を使うと、対応するファイルハンドラーが出力を再構築する際に、それぞれの扱いを明示できます。
これらは .lingo/config.json のファイルエントリーに指定するオプションです。ファイルの選択やキーの更新要求には使いません。それらは翻訳スコープで指定します。
| 制御 | 出力時の動作 |
|---|---|
lockedKeys | ソースの値を翻訳せずにコピーします。 |
preservedKeys | 既存の翻訳先の値があれば保持します。 |
ignoredKeys | 対応する形式の出力から、選択したコンテンツを除外します。 |
injectLocale | 指定した位置に翻訳先ロケールを書き込みます。 |
各値の管理元を決める #
{
"pattern": "locales/en.json",
"lockedKeys": ["product.id"],
"preservedKeys": ["legal.notice"],
"ignoredKeys": ["internal.note"],
"injectLocale": { "enabled": true, "key": "meta.locale" }
}この例では、製品識別子はソースから取得し、既存の法的通知は翻訳先のものを保持し、内部メモは出力から除外します。ロケール注入では、翻訳先ロケールを meta.locale に書き込み、必要に応じて不足しているオブジェクトコンテナーを作成します。配列内の位置を指定する場合は、既存の配列を用意し、既存の要素か末尾の直後の位置を選択してください。要素間に空きを作るパスや、互換性のない値を経由するパスはエラーになります。
保持機能は、存在しない人手の翻訳を作成するものではありません。通常の差分処理でも、既存の翻訳先コンテンツを使い、変更のないキーに加えられた編集を維持します。preservedKeys は、この動作に加えて明示的な保護を適用します。ただし、ソースや JSON キー名が変更された場合は、新たな作業が必要になることがあります。
パスと制御の重複 #
JSON/JSONC の制御では、checkout.submit や items[0].title のように、ドット区切りの名前と角括弧内のインデックスを使います。保護対象のパスには、その配下も含められます。キー名自体にドットが含まれる場合は、$['checkout.submit'] のように引用符で囲んだ JSONPath プロパティを使ってください。lingo push は、旧 CLI 向けに / を使って記述されたリストも読み取れます。/ の間にある名前はそれぞれ一つの名前として扱われるため、checkout/submit は checkout.submit と同じ意味になり、common/error.message は common 配下のキー error.message を指します。legal/Terms%20of%20use のようにパーセントエンコードされた名前はデコードされます。/ を含まないパターンはドット区切りのパスとして扱われ、デコードされません。そのため、エンコードされた単一の名前は $['Terms of use'] のように JSONPath で記述してください。/ を含むパターンはすべてこの方法で読み取られるため、名前に / を含むキーには、$.routes['/about'].title のような JSONPath が必要です。internal/* のように末尾に * を付けると、旧 CLI と同様に、internal 直下の値が対象になりますが、そこに入れ子になっているオブジェクトや配列は対象になりません。旧 CLI では - または . が続くキーにも一致していたため、legal/terms は legal/terms-short も対象にしていました。この前方一致は廃止されました。該当するキーは個別に列挙してください。GitHub App はスラッシュ形式を受け付けません。同じ設定を GitHub App で読み取る場合は、これらのリストをドット区切りか JSONPath で記述してください。この形式についてはスコープで説明しています。
同じ位置では、無視ルールによって値が削除されます。注入されたロケール値も例外ではありません。ロケール注入は、ロックや保持よりも優先されます。また、ロックは保持よりも優先されるため、両方のリストにあるキーにはソースの値が使われます。上位の要素が無視される場合、その配下も削除されます。できるだけ各値の管理元を一つにし、オブジェクトや配列内でルールが重複する場合は出力を確認してください。
ファイル全体を強制処理すると、サーバーに送信される現在の翻訳先の成果物がクリアされます。その翻訳先のコンテキストがなければ、保持ルールでも以前に人が作成した文面を維持できません。強制的に置き換える前に、復元できるコピーを保存してください。
ハンドラーの対応範囲 #
JSONとJSONCは、4種類すべての制御に対応しています。TypeScript、PHP、YAML、ロケールルートのYAMLはロック、保持、無視に対応し、stringsdictはロックと保持に対応しています。Javaプロパティはロック、保持、無視、キーのスコープに対応し、従来のCLIと同様に各パターンをキー全体と照合します。CSVは、3種類のキールールのいずれにも対応していません。CLIとGitHub Appは、lockedKeys、preservedKeys、ignoredKeysのいずれかが設定されたCSVエントリを拒否します。出力時の動作については、選択したフォーマットのリファレンスをご覧ください。
短縮パス形式では、セグメント全体を表す *、数値インデックス、空の角括弧を使用できます。部分的なワイルドカードは使用できません。lingo push では、三つのキールールリストでスラッシュ形式も使用できますが、GitHub App や注入先の位置指定では使用できません。句読点や記号を含む名前をそのまま指定するには、引用符で囲んだ JSONPath プロパティを使ってください。明示的な $ クエリはそのまま渡されます。注入先は一か所にする必要があり、注入を有効にした場合の既定のキーは language です。