键控制
选择值的来源:源内容、现有目标内容、翻译或语言区域元数据。
有些目录值需要在各语言中保持一致,有些则应采用人工维护的目标值。支持这些控制的文件处理器重建输出时,键控制可明确指定每个值的处理方式。
这些选项用于配置 .lingo/config.json 中的文件条目,不负责选择文件或请求刷新键;这些操作由翻译范围负责。
| 控制 | 输出行为 |
|---|---|
lockedKeys | 直接复制源值,不进行翻译。 |
preservedKeys | 已有目标值时,保留该值。 |
ignoredKeys | 从支持此控制的格式输出中移除选定内容。 |
injectLocale | 在指定位置写入目标语言区域。 |
为每个值明确归属 #
{
"pattern": "locales/en.json",
"lockedKeys": ["product.id"],
"preservedKeys": ["legal.notice"],
"ignoredKeys": ["internal.note"],
"injectLocale": { "enabled": true, "key": "meta.locale" }
}在此示例中,产品 ID 使用源内容中的值,法律声明保留目标内容中的现有版本,内部备注则不输出。语言区域注入会将目标语言区域写入 meta.locale,并在需要时创建缺失的对象容器。对于数组位置,请提供已有数组,并选择现有元素或紧接数组末尾的位置;如果路径会造成索引空缺或经过不兼容的值,操作将失败。
保留功能无法凭空创建人工翻译。常规增量处理本就会利用现有目标内容,保留对未更改的键所做的编辑;preservedKeys 则在此基础上提供显式保护。源内容发生变化或 JSON 键被重命名时,仍可能需要重新处理。
路径与控制规则重叠 #
JSON/JSONC 控制使用点分隔的名称和方括号索引,例如 checkout.submit 或 items[0].title。受保护的路径可以覆盖其后代节点。如果键名本身包含点号,请使用带引号的 JSONPath 属性,例如 $['checkout.submit']。lingo push 也能读取为早期 CLI 编写、使用 / 的列表:/ 之间的每个名称都视为一个整体,因此 checkout/submit 等同于 checkout.submit,而 common/error.message 指定的是 common 下的键 error.message。采用百分号编码的名称(例如 legal/Terms%20of%20use)会被解码;不含 / 的模式按点分隔路径处理,不会被解码,因此单个编码名称应写成 JSONPath,例如 $['Terms of use']。由于所有包含 / 的模式都会按此方式读取,名称中包含 / 的键也需要使用 JSONPath,例如 $.routes['/about'].title。末尾的 *(如 internal/*)会覆盖 internal 直属的值,但不覆盖其中嵌套的对象或数组,这与早期 CLI 的行为一致。早期 CLI 还会匹配后面接有 - 或 . 的键,因此 legal/terms 会覆盖 legal/terms-short。现在已取消这种前缀匹配,请单独列出这些键。GitHub App 不接受斜杠形式:当 GitHub App 读取同一配置时,请使用点分隔形式或 JSONPath 编写这些列表。范围介绍了这种形式。
在同一位置,忽略规则会移除该值,包括注入的语言区域值。语言区域注入的优先级高于锁定和保留,而锁定的优先级高于保留,因此同时出现在锁定和保留列表中的键会使用源值。忽略祖先节点时,其后代节点也会一并移除。请尽可能为每个值指定唯一归属;当规则在对象或数组中重叠时,请检查输出。
对整个文件执行强制处理,会清空发送到服务器的当前目标产物。缺少这份目标上下文时,保留规则无法保留之前的人工表述。强制替换前,请保存一份可恢复的副本。
处理器的支持范围 #
JSON 和 JSONC 支持全部四种控制功能。TypeScript、PHP、YAML 和语言区域根目录 YAML 支持锁定、保留和忽略;stringsdict 支持锁定和保留。Java 属性文件支持锁定、保留、忽略和键作用域,并沿用之前 CLI 的方式,将每个模式与完整的键进行匹配。CSV 不支持这三种键规则:如果 CSV 条目设置了 lockedKeys、preservedKeys 或 ignoredKeys,CLI 和 GitHub App 都会拒绝该条目。请查阅所选格式的格式参考,了解其输出行为。
短路径形式支持占据整个路径段的 *、数字索引和空方括号,不接受局部通配符。使用 lingo push 时,三个键规则列表也接受斜杠形式,但 GitHub App 和注入位置不接受。对于本身包含标点符号的名称,请使用带引号的 JSONPath 属性;显式的 $ 查询会原样传递。注入需要指定一个位置,启用时默认使用键 language。