JSON

翻译嵌套字符串值,灵活控制哪些路径要复制、保留、排除或更新。

在 JSON 资源目录中,应用通过键查找并显示对应的值。json 文件处理器会修改字符串值,同时保持对象键、数组位置、数字、布尔值和 null 值这些数据不变。它会以当前源文件为基础重建目标文件,填入新译文或沿用的目标文本。

处理器支持嵌套的对象和数组资源目录,也支持根节点为字符串的情况。CLI 会根据 .json 推断出 json。你可以通过 CLI 配置或 GitHub App 配置源文件。

哪些内容会成为翻译任务 #

例如:

json
{
  "checkout": {
    "title": "Complete your order",
    "delivery": "Delivery within {days} days"
  },
  "plans": [
    { "name": "Personal", "seats": 1 },
    { "name": "Team", "seats": 10 }
  ],
  "enabled": true
}

处理器会选中 checkout.title、checkout.delivery、plans[0].name 和 plans[1].name,并保持 seats 中的数字和 enabled 布尔值不变。对于字符串类型的标识符,请明确设置保护规则:值的 JSON 类型只能告诉处理器它是文本,并不能说明它是否供人阅读。

简写路径用点号逐层访问对象,用方括号指定数组位置:checkout.title 选中嵌套值,plans[0].name 选中第一个方案的名称。如果键名本身就是 checkout.title,请使用带引号的 JSONPath 形式 $['checkout.title']。选择语法请参阅键控制。

更新时如何复用现有译文 #

增量运行使用三种不同的输入:

输入作用
当前源文件定义新输出的结构和字符串。
上一次的源文件用于判断对应路径上的源字符串是否发生变化。
现有目标文件提供可沿用的译文。

当上一次的源文件和现有目标文件都可用时,新增或更改的源字符串会成为翻译任务。未更改的源字符串可以复用对应路径上的现有目标值。即使两个键的英文文本相同,它们仍是独立记录;上下文不同,已采纳的译文也可能不同。

例如,仅更改 checkout.title 并不意味着需要重新翻译 checkout.delivery。如果后者的源值未变,且目标值可用,就可以沿用该目标值。即使没有新字符串需要翻译,数字或其他结构数据的变化仍可能要求重建文件。

请将上一次的源文件与已采纳的目标文件配对保存。缺少其中任何一个,处理器都会将这些字符串视为首次处理。CLI 的 Lockfile 和缓存会在多次运行之间关联这些输入。

选择受保护路径的处理方式 #

不同的控制方式会产生不同的输出结果:

控制方式翻译行为输出行为
锁定路径不参与翻译。使用当前源文件中的值。
保留路径不参与翻译。如果现有目标文件中存在该路径,则保留其值;否则保留源值。
忽略路径不参与翻译。从生成的目标文件中移除该路径。
语言区域注入配置的语言区域字段不参与翻译。将目标语言区域写入该字段。

如果所有语言区域都必须使用源值,请锁定共享标识符。如果每个语言区域都有自己的目标地址,请保留目标专用的 URL。如果某条备注仅供源文件使用,不应出现在译后文件中,请忽略它。这些选项不能一概理解为“不翻译”。

对于同一路径,锁定优先于保留,因此同时出现在这两个列表中的值会取自源文件。忽略会移除该值,即使它也被锁定、保留或选中用于语言区域注入。在注入位置,语言区域注入优先于锁定和保留。尽量让每个值只由一种规则控制;当规则在对象或数组中重叠时,请检查输出。

移除数组元素会使后续元素的位置前移。请从数据层面审核生成的数组,而不只是检查译文。语言区域注入可以创建缺失的对象容器。写入数组时,请使用现有元素的位置,或紧接数组末尾的下一个位置;如果路径会产生空缺或经过不兼容的值,写入就会失败。

通过 CLI 文件条目字段或 GitHub 文件条目选项设置这些控制方式。

作用范围与重建限制 #

键刷新会将选中的译文合并到现有目标文件中。未选中的目标值、仅存在于目标文件中的键以及已省略的内容都会保持原状;范围之外仅存在于源文件中的键不会被添加。写入数组时不能产生空缺。例如,选中第二个数组元素,并不会自动补齐缺失的第一个元素。局部更新后,请检查完整的目标文件。

JSON 输出在序列化时使用两个空格缩进,并在末尾添加换行符。空白字符或注释不保证能逐字节保留。如果源文件包含注释,请阅读 JSONC,并在将重写后的文件视为等效文件之前,确认使用该文件的系统有何要求。

翻译工作流会检查其支持的占位符和 ICU 结构,包括参数是否更改或缺失。请查看报告中的警告或失败信息,再用应用中的值渲染已采纳的模板。这些检查并不判断译文是否表达了预期含义。

在应用中加载输出,并使用有代表性的值进行测试。检查受保护路径是否保留了预期的源数据或目标数据,以及交付信息在替换变量后是否仍传达相同的承诺。解析验证的是 JSON 语法;渲染和阅读验证的才是用户实际收到的信息。