キーの保持

Lingo.dev CLIを使用すると、特定の翻訳キーを保持して、一度初期化された後、その後のCLI操作で上書きされないようにすることができます。保持されたキーは、プレースホルダーとしてソースからコピーされ、自動翻訳の更新から保護されます。

キーを保持すると、CLIはソース値で初期化し、今後の翻訳実行時にそれらをスキップします。

キー保持の設定

i18n.jsonのバケット設定にpreservedKeysを追加します。

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms", "marketing/tagline"]
    }
  }
}

preservedKeys配列は、スラッシュ(/)表記を使用してネストされたキーを指定し、アスタリスク(*)を使用して複数のキーに一致させます。

キー保持の仕組み

翻訳処理中、Lingo.dev CLIは以下を実行します。

  1. 保持されたキーを識別 — 設定から保持されたキーを特定します
  2. 翻訳から除外 — 保持されたキーは翻訳エンジンに送信されません
  3. 不足しているキーを初期化 — 新しいターゲットファイルのプレースホルダーとしてソース値をコピーします
  4. 既存の値を保護 — 手動で翻訳されたコンテンツを変更せずに保持します

ワークフローの例:

// locales/en.json (source)
{
  "welcome": "Welcome to our platform",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

保持されたキーの設定:

{
  "preservedKeys": ["legal/privacy", "legal/terms"]
}

生成されたスペイン語翻訳(初回実行):

// locales/es.json (generated)
{
  "welcome": "Bienvenido a nuestra plataforma",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

welcomeキーは翻訳されます。legalセクションは、後で手動翻訳するためにそのままコピーされます。

ネストされたキーパス

スラッシュ(/)表記を使用して、任意の深さのキーを保持します。

{
  "preservedKeys": [
    "legal/privacy/full",
    "legal/terms/conditions",
    "marketing/campaigns/holiday"
  ]
}

この表記は、複雑なネスト構造でも機能します。

// Source structure
{
  "legal": {
    "privacy": {
      "full": "Full privacy policy text..."
    }
  }
}

パスlegal/privacy/fullは、この特定のネストされたキーを保持します。

ドットを含むキー

スラッシュ表記は、名前にドットを含むキーを処理します。

// Source with dotted key names
{
  "legal": {
    "privacy.policy": "Privacy policy content",
    "terms.of.service": "Terms of service content"
  }
}

次のコマンドでこれらのキーを保持します:

{
  "preservedKeys": ["legal/privacy.policy", "legal/terms.of.service"]
}

複数のバケットタイプ

異なるファイル形式は、異なる保持キーを持つことができます:

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms"]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "preservedKeys": ["compliance/gdpr", "compliance/ccpa"]
    }
  }
}

各バケットタイプは、コンテンツ構造に基づいて独自の保持キーリストを維持します。

キー保持とキーロックの違い

キー保持とキーロックは異なる目的を持ちます:

キー保持(preservedKeys):

  • キーはソース値をプレースホルダーとして一度だけ初期化されます
  • 既存のターゲット値はCLIによって上書きされることはありません
  • 手動翻訳や法的レビューが必要なコンテンツに使用されます

キーロック(lockedKeys):

  • キーは翻訳処理に含まれますが、値は変更されません
  • ロックされたキーは常にソース値と完全に一致します
  • 技術的な識別子、コンポーネント名、または一貫性を保つ必要がある値に使用されます

比較例:

// Source file
{
  "welcome": "Welcome",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

// Configuration
{
  "lockedKeys": ["system/component"],
  "preservedKeys": ["legal/privacy"]
}

// Generated target file
{
  "welcome": "Bienvenido",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

legal/privacyをスペイン語に手動翻訳した後、その後の実行では手動翻訳が保持されます。system/componentキーは、ターゲットファイルの内容に関係なく、常に英語のままです。