密钥保护 - Lingo.dev CLI

Lingo.dev CLI 支持对特定翻译 key 进行保护，使其仅初始化一次，后续 CLI 操作不会覆盖。被保护的 key 会从源语言复制为占位符，并在自动翻译更新时受到保护。

启用密钥保护后，CLI 会用源语言内容初始化这些 key，并在后续翻译过程中跳过它们。

配置密钥保护

在 preservedKeys 中，将其添加到 i18n.json 的 bucket 配置中：

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

preservedKeys 数组使用斜杠（/）表示嵌套 key，星号（*）可用于匹配多个 key。

密钥保护机制说明

在翻译处理过程中，Lingo.dev CLI 会：

识别受保护的 key —— 来自你的配置
排除这些 key 的翻译 —— 受保护的 key 不会被发送到翻译引擎
初始化缺失的 key —— 对新目标文件用源内容作为占位符
保护已有内容 —— 手动翻译的内容不会被覆盖

示例工作流：

// 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 key 会被翻译，而 legal 部分会原样复制，供后续手动翻译。

嵌套 key 路径

使用斜杠（/）表示法可保护任意层级的 key：

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

该表示法适用于复杂嵌套结构：

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

路径 legal/privacy/full 可保护该嵌套 key。

带点的 key

斜杠表示法同样适用于名称中包含点的 key：

// 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 键无论目标文件内容如何，始终保持为英文。