JSON 本地化时哪些能翻，哪些绝对不能动

本文使用合成样本演示处理方法。代码已通过隔离环境中的示例检查；这不代表对所有真实文件或产品效果的保证。处理重要文件前，请保留原件，并按文中的边界与验收项复核。 页面上的按钮翻成英文了，程序却找不到配置项。这种故障常出在 JSON 本地化：把对象里的每个字符串都交给翻译器，连键名、路由和业务编码也一起变了。更稳妥的做法不是猜哪些字符串像人话，而是明确允许翻译哪些路径。 从字段路径开始，而不是遍历所有字符串 把 buttons.save 看成一个地址，比看到字符串“保存”就替换更可靠。同一句话可能同时出现在界面文案、日志样例和测试用例里，三处未必都需要翻译。路径也应使用元组或 JSON Pointer 一类无歧义的表示；用点简单拼接时，键名本身含点会产生歧义。 下面限定两个具体路径，其他内容原样保留。它是本文的本地化策略，不是 JSON 格式本身的要求。合成样本里既有界面文本，也有一个绝不能改动的路由值，方便检查边界。 一次只改明确允许的值 import copy source = {"buttons": {"save": "保存", "cancel": "取消"}, "route": "/settings", "version": 1} approved = {("buttons", "save"): "Save", ("buttons", "cancel"): "Cancel"} def apply_texts(document, replacements): result = copy.deepcopy(document) for path, translated in replacements.items(): if not path or not isinstance(translated, str): raise ValueError("invalid replacement") parent = result for key in path[:-1]: parent = parent[key] key = path[-1] if key not in parent or not isinstance(parent[key], str): raise ValueError("target must be an existing string") parent[key] = translated return result result = apply_texts(source, approved) assert result["buttons"]["save"] == "Save" assert result["route"] == source["route"] assert source["buttons"]["save"] == "保存" try: apply_texts(source, {("version",): "one"}) except ValueError: pass else: raise AssertionError("numeric field must be rejected") 示例只有对象层级，没有实现数组索引，也没有调用翻译服务。提交到真实管线时，允许路径清单应在翻译前确定，不能让生成译文的一方同时扩大自己的修改范围。深拷贝使输入对象不被原地污染，但它不是事务系统；持久化仍需单独设计。 验收要看没改的部分 检查 正常结果 异常时的动作 键名集合 与源文件一致 阻止覆盖原文件 未授权路径 值保持不变 找出越界修改 目标字段类型 仍是字符串 拒绝隐式类型转换 缺失路径 明确报错 更新源版本，不自动创造字段 只验证“目标语言出现了”是不够的。还应保存源文件哈希和路径清单；如果源文件更新后路径已删除，旧译文不能凭相似字段名自动写回。占位符、HTML 片段和 URL 即使位于允许的文案字段内，也需要下一层保护规则。 数组、空值和重复键要另外考虑 数组中元素重排后，索引不一定还指向原来那条文案。有稳定 ID 时，优先用 ID 做映射。 null 不是空字符串，不应为了方便翻译就替换成文字“空”。此外，普通 JSON 解析完成后可能已经丢失重复键信息，若要拒绝重复键，应在解析阶段处理，而不是等翻译结束再查。 这个例子适合结构明确的配置本地化，不是任意 JSON 自动翻译器。翻译验收时，先确认结构和受保护字段没有变化，再讨论语言是否自然，排查顺序会清楚得多。 用于实际文档交付 可以把允许路径、原文和译文做成一份审校清单。用 OmniDoc（产品入口） 的文档翻译入口处理真实文件时，也应沿用同样的边界：可读文案可以改变，程序契约不该被顺手重写。平台能力与本地校验器的职责应分开说明，不假定上传后会自动完成本文的路径验证。 参考： Python JSON 文档 。 - 1 -