キー制御

通常は、ファイル内のすべての文字列を翻訳したいはずです。ですが、ブランド名、機能フラグ、法務文言、内部向けの不要データなど例外もあります。そうしたケース向けに、CLI ではファイルごとに 3 つの制御を用意しており、.lingo/config.json 内の files[] エントリで設定できます。

いずれも、ファイル構造をそのまま反映した ドット/ブラケット記法 のキーパスを受け取ります。

{
  "files": [
    {
      "pattern": "content/en/app.json",
      "lockedKeys": ["meta.version"],
      "preservedKeys": ["legal.terms"],
      "ignoredKeys": ["internal.debug"]
    }
  ]
}

Lock — どのロケールでも同じ値を保つ#

lockedKeys は、ソース値を翻訳せずにすべてのターゲットファイルへコピーします。ロケールをまたいで、バイト単位で完全に同一である必要がある値に使います。

{
  "pattern": "content/en/app.json",
  "lockedKeys": ["meta.version", "config.apiUrl"]
}

de.json と fr.json には、正確なソース文字列がそのまま入るため、meta.version になります。ソースを変更すると、次回の lingo push で新しい値がすべてのロケールに反映されますが、翻訳はされません。

Preserve — 手動で書いたターゲットを守る#

preservedKeys を指定すると、すでに存在するターゲット値をエンジンが上書きしなくなります。人手で翻訳する必要があるキー、たとえば法務テキストやコンプライアンス文言、レビュー済みでモデルに触れさせたくない内容に使います。

{
  "pattern": "content/en/settings.jsonc",
  "preservedKeys": ["featureFlags"]
}

エンジンは初回の翻訳時にソースからそのキーを投入し、その後の実行ではあなたの編集をそのまま保持します。下記の overrides と比較してください。

Ignore — 出力からキーを除外する#

ignoredKeys は、そのキーをターゲットファイルから完全に取り除きます。翻訳もコピーも書き込みもされません。翻訳済みビルドに含めるべきではないデバッグ文字列、内部フラグ、テストデータに使います。

{
  "pattern": "content/en/app.json",
  "ignoredKeys": ["internal.debug", "dev.testData"]
}

overrides と preserve の違い#

既存のターゲット値が実行後も保持される方法は 2 つあります。

• Preserve（preservedKeys）— 宣言的な方法です。キーは設定によって、すべてのロケールで恒久的に保護されます。
• ローカル編集 — lingo push は各ターゲットのハッシュをロックファイルと比較します。ターゲットファイルを手動で編集していた場合、push はそれを skipped (local edits) として報告し、そのまま保持します。上書きするには --force（スコープ付き）を渡します。lingo push を参照してください。

恒久的に、かつロケール全体で保護したいなら preservedKeys を使い、単発の手動調整にはローカル編集検出を使ってください。

レガシー CLI からの移行#

レガシー CLI には キーのリネーム（キー ID が変わったときに翻訳を引き継ぐ機能）もありました。ただし、これは現在の CLI には含まれていません。翻訳状態はファイルハッシュ単位で追跡されるため、キー名を変更すると次回の push で再翻訳されます。Lock、Preserve、Ignore はそのまま引き継がれますが、変更点が 1 つあります。パスは古いスラッシュ記法 meta/version ではなく、ドット/ブラケット記法（meta.version）を使います。