键级控制

大多数时候，你会希望文件里的每个字符串都被翻译。但总有例外——品牌名、功能开关、法务文案、内部杂项——CLI 为每个文件提供了三种控制方式，可在 .lingo/config.json 中的 files[] 条目里设置。

这三种方式都接受采用点号/方括号表示法的键路径，与文件结构一一对应：

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

锁定——让值在所有地方保持一致#

lockedKeys 会把源值直接复制到每个目标文件中，不经过翻译。适用于那些必须在所有语言环境中保持逐字节一致的值：

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

de.json 和 fr.json 会用完全一致的源字符串进行 meta.version。源值一旦变更，下一次 lingo push 就会把新值同步到所有语言环境中，且依然不会翻译。

保留——保护手写的目标文本#

preservedKeys 会告诉引擎：只要目标值已经存在，就永远不要覆盖。适用于某个键需要人工翻译的场景——法务文本、合规文案，或任何你已经审核过、不希望模型改动的内容：

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

首次翻译时，引擎会先用源值填充该键；之后无论运行多少次，都会保留你的修改不动。可与下方的 overrides 对比理解。

忽略——从输出中移除该键#

ignoredKeys 会将该键彻底从目标文件中移除——不会翻译、不会复制，也不会写入。适用于调试字符串、内部标记和测试数据，这些内容不该出现在翻译后的构建中：

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

overrides 与 preserve#

现有目标值在一次运行后得以保留，主要有两种方式：

• Preserve（preservedKeys）——声明式。这个键会通过配置被持续保护，适用于所有语言环境，且长期生效。
• 本地编辑——lingo push 会将每个目标文件的哈希与 lockfile 对比。如果你手动修改过目标文件，push 会将其标记为 skipped (local edits)，并保持不动。传入 --force（配合作用域）即可覆盖。参见 lingo push。

如果这种保护是长期的，且适用于所有语言环境，就用 preservedKeys；如果只是一次性的手动微调，则依赖本地编辑检测即可。

从旧版 CLI 迁移#

旧版 CLI 还支持键重命名（即键 ID 变更时沿用已有翻译）。这一能力不属于当前 CLI——翻译状态按文件哈希跟踪，因此一旦重命名某个键，下一次 push 时就会重新翻译。lock、preserve 和 ignore 依然保留，但有一处变化：路径现在使用点号/方括号表示法（meta.version），而不再是旧版的斜杠表示法（meta/version）。