键锁定

Lingo.dev CLI 允许你锁定特定的翻译键，使其在所有语言中的值保持一致。锁定键后，CLI 会在翻译处理时跳过这些键，并将源语言的值直接复制到所有目标文件中。

设置键锁定

在 lockedKeys 中添加到你的 bucket 配置文件 i18n.json ：

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["system/component", "config/engine", "modules/processor"]
    }
  }
}

lockedKeys 数组使用正斜杠（/）表示嵌套键路径，使用星号（*）匹配多个键。

键锁定的工作原理

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

  1. 识别配置中的锁定键
  2. 将其排除在翻译之外 —— 锁定内容不会被发送给 AI 模型
  3. 将源语言值直接复制 到所有目标文件
  4. 确保所有语言一致性

示例工作流：

// locales/en.json (source)
{
  "welcome": "Welcome to our platform",
  "system": {
    "component": "Lingo.dev CLI",
    "processor": "Translation Engine"
  },
  "config": {
    "engine": "Lingo.dev Engine"
  }
}

使用锁定键配置：

{
  "lockedKeys": ["system/component", "system/processor", "config/engine"]
}

生成的西班牙语翻译：

// locales/es.json (generated)
{
  "welcome": "Bienvenido a nuestra plataforma",
  "system": {
    "component": "Lingo.dev CLI",
    "processor": "Translation Engine"
  },
  "config": {
    "engine": "Lingo.dev Engine"
  }
}

只有 welcome 会被翻译，锁定的键内容与源语言保持一致。

如果没有键锁定，"Lingo.dev Engine" 可能会被错误翻译为西班牙语的 "Motor de Lingo.dev" 或日语的 "Lingo.devエンジン"，而在本例中我们并不希望这样。

嵌套键路径

使用正斜杠（/）表示法可以锁定任意深度的键：

{
  "lockedKeys": [
    "system/engine/component",
    "modules/ai/processor",
    "config/translation/handler"
  ]
}

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

// Source structure
{
  "system": {
    "engine": {
      "component": "Lingo.dev Engine"
    }
  }
}

路径 system/engine/component 锁定了组件名称的值。

含点的键

正斜杠表示法可以处理名称中包含点的键：

// Source with dotted key names
{
  "modules": {
    "ai.translation": "AI Translation",
    "content.processor": "Content Processor"
  }
}

使用以下方式锁定这些 key：

{
  "lockedKeys": ["modules/ai.translation", "modules/content.processor"]
}

多种 Bucket 类型

不同的文件格式可以有不同的锁定 key：

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["config/engine", "system/component"]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "lockedKeys": ["service/name", "module/title"]
    }
  }
}

每种 bucket 类型会根据内容结构维护各自的锁定 key 列表。

数组值

对于值为数组的 key，在 key 名后添加 /*：

// Source file
{
  "navigation": {
    "menuItems": ["Home", "About", "Contact"],
    "title": "Main Navigation"
  }
}

使用以下方式锁定该数组：

{
  "lockedKeys": ["navigation/menuItems/*"]
}

结果：

// locales/es.json
{
  "navigation": {
    "menuItems": ["Home", "About", "Contact"],
    "title": "Navegación Principal"
  }
}