JSON 文件怎么翻译?保留键名与占位符的两种稳妥做法

意扣

导读

翻译 JSON 多语言词条或商品数据时,如何防止键名被翻、引号报错或占位符损坏?详解 XLSX 表格中转去重法与 Python 递归脚本方案。

关键词:translate json file; JSON文件翻译; 翻译JSON保留键名; i18n多语言JSON翻译; JSON本地化

直接把 .json 文件的内容复制进普通网页翻译器,十有八九会让前端或后端直接报错崩溃。因为 JSON 的键名(Key)和字符串值(Value)都用英文双引号包裹,普通文本翻译器分不清哪些是代码要读取的字段名、哪些是给用户看的文案,往往把 "checkout_button" 翻成别的语言,把英文直引号替换成中文弯引号(“ ”),甚至把 {count}、{{name}} 这类动态变量一起改掉。要想安全地翻译 JSON 文件,核心原则只有一条:先把字符串值与 JSON 结构剥离开,翻译完再拼回去——要么展开成 .xlsx 表格交由文档翻译处理并去重审校,要么用递归脚本只遍历字符串叶子节点。

在展开具体步骤前,我们先坦诚交代产品的格式边界:意扣(Equalang)的文档翻译页面支持 PDF、DOCX、PPTX、XLSX、EPUB、HTML 和 TXT 等格式,不支持直接上传 .json 文件(虽然录音录像任务可以导出 .json 格式的字幕文字稿)。下面分享我们团队在实际本地化工作中最常用的两套无损方案。

为什么直接复制 JSON 去翻译一定会坏?

根据 IETF 制定的 JSON 规范 RFC 8259,对象的键名和字符串值采用完全相同的双引号语法(例如 "checkout_button": "Pay now"),对象末尾不允许出现多余逗号,且字符串内部如果包含双引号,必须转义为 \"。普通文本翻译框没有语法解析器,把整段 JSON 当成散文处理时,立刻会踩中三个坑:

  • 键名被翻译,代码找不到字段: 前端组件明明在读 t('checkout_button'), 翻译后键名变成了 "结账按钮" 或法语 "bouton_paiement",页面直接渲染出空白甚至报错。
  • 引号与转义被破坏,无法通过 JSON.parse(): 翻译成中文时,直引号常被替换成全角弯引号 “ ”;翻译成法语或德语时,译文里夹带的双引号一旦漏掉 \" 转义,整个文件就不再是合法 JSON。
  • 插值占位符变形: 多语言框架依赖 {count}、{{username}} 或 %s 在运行时注入数据。一旦翻译器把花括号里的变量名翻成了中文,或者在花括号里多塞了空格,线上页面就会把坏掉的占位符原样吐给用户。

方法一:将 JSON 词条展开为 XLSX,用意扣翻译后再拼回

如果你手头是一份前端多语言包(如 en.json)或电商商品目录,希望翻译后能由产品、运营同事对照检查一遍再上线,把 JSON 字符串提取成 .xlsx 表格中转是最省心、也最省用量的办法。

为什么要借道 .xlsx 而不是直接拼文本?把展开后的表格传到意扣的文档翻译时,有三个正好契合 JSON 本地化的特性:

  1. 重复词条只翻译一次、只计费一次: 多语言 JSON 的不同模块下常有大量重复的按钮文案(比如几十处 Cancel、Save、Confirm)。在 XLSX 表格里,重复出现的单元格文字只翻一次,既省下积分,又保证全站按钮译法统一。
  2. 纯数字原样保留: 表格里的纯数字编号、价格、排序权重不会进入翻译引擎,翻译后原封不动写回。
  3. 翻译工作台左右并排核对: 翻译完成后,可以在网站的翻译工作台(Translation workspace)里直接打开,左边原文、右边译文并排同步滚动,方便一眼揪出过长或语境不符的 UI 词条。
意扣翻译后的 XLSX 表格保持列位整齐、纯数字不动且重复词条只计费一次
将 JSON 词条展开为两列 XLSX 交由意扣翻译(再将原英文键名列拼回导出 JSON),既能给重复按钮文案去重省积分,也能彻底避免 JSON 语法破损

第一步:用脚本把字符串值抽成两列 XLSX(键名留在本地)

为了从根源上杜绝键名被翻译,我们用一段十几行的 Python 脚本(需安装 openpyxl)把嵌套 JSON 拍平:将完整的键路径(key_path)、布尔值、数字和 null 保存在本地的 keys_map.json 里,只把行号和需要翻译的字符串值写入 to_translate.xlsx。

import json
import openpyxl

def flatten_json(node, prefix="", rows=None):
    if rows is None:
        rows = []
    if isinstance(node, dict):
        for k, v in node.items():
            path = f"{prefix}.{k}" if prefix else k
            flatten_json(v, path, rows)
    elif isinstance(node, list):
        for idx, v in enumerate(node):
            flatten_json(v, f"{prefix}[{idx}]", rows)
    else:
        rows.append({"path": prefix, "value": node, "is_str": isinstance(node, str)})
    return rows

with open("en.json", "r", encoding="utf-8") as f:
    source_data = json.load(f)

flat_rows = flatten_json(source_data)
with open("keys_map.json", "w", encoding="utf-8") as f:
    json.dump(flat_rows, f, ensure_ascii=False, indent=2)

wb = openpyxl.Workbook()
ws = wb.active
ws.title = "Strings"
for idx, item in enumerate(flat_rows, start=1):
    if item["is_str"]:
        ws.append([idx, item["value"]])

wb.save("to_translate.xlsx")

这样生成的 to_translate.xlsx 中,A 列是纯数字行号(1、2、3……意扣不会翻译纯数字),B 列是待翻译的文案,你的英文键名根本没有出现在表格里。

第二步:上传 XLSX 到意扣翻译并对照检查

打开意扣文档翻译页面,上传 to_translate.xlsx 并选择目标语言。文档翻译目前支持中文、英文、日语、韩语、西班牙语、法语等多种语言,源语言支持自动识别。如果你要一次准备多国语言包,可以一个接一个上传文件(同一账号同时最多处理 3 份文档,其余自动排队)。新账号注册即送 200 积分(计费明细见价格页面),足够先拿手头的语言包试跑验证。

如果你的数据原本是从数据库导出的逗号分隔文件,也可以参考我们的CSV 文件翻译指南处理分隔符与编码。

第三步:校验 {占位符} 并还原为标准 JSON

从意扣下载译文表格(假设命名为 translated.xlsx)后,运行下面这段还原脚本。它会把译文按行号填回 keys_map.json,自动比对原文和译文里的 {...} 或 %s 占位符是否一致,最后由 Python 的 json.dump() 严格按照 RFC 8259 规范输出转义合法的 JSON 文件:

import json
import re
import openpyxl

PLACEHOLDER_RE = re.compile(r"\{\{?[a-zA-Z0-9_]+\}?\}|%[sd]")

with open("keys_map.json", "r", encoding="utf-8") as f:
    flat_rows = json.load(f)

wb = openpyxl.load_workbook("translated.xlsx")
ws = wb["Strings"]
translated_by_id = {int(row[0]): str(row[1]) for row in ws.iter_rows(values_only=True) if row[0] is not None}

for idx, item in enumerate(flat_rows, start=1):
    if item["is_str"] and idx in translated_by_id:
        src_tokens = set(PLACEHOLDER_RE.findall(item["value"]))
        tgt_text = translated_by_id[idx]
        tgt_tokens = set(PLACEHOLDER_RE.findall(tgt_text))
        if src_tokens != tgt_tokens:
            print(f"占位符警告 [{item['path']}]: 原文 {src_tokens} -> 译文 {tgt_tokens}")
        item["value"] = tgt_text

校验无误后,将路径列表折叠回嵌套字典并调用 json.dump(..., ensure_ascii=False, indent=2) 即可写出目标语言 JSON。

方法二:Python 递归遍历脚本(直接锁定占位符)

如果你不需要人工审校表格,而是想在命令行或 CI/CD 流水线里直接跑通 JSON 转换,可以用 Python 把 JSON 解析成内存里的字典和列表,只对字符串叶子节点发起翻译(开发者也可查看意扣的开发者工具与接入说明)。

核心技巧是在发往翻译函数前,先把 {count}、{{name}} 等变量替换成无意义的占位代号(如 __VAR_0__),拿到译文后再原样换回来:

import json
import re

TOKEN_PATTERN = re.compile(r"(\{\{?[a-zA-Z0-9_]+\}?\})")

def translate_with_locked_vars(text, translate_fn):
    tokens = TOKEN_PATTERN.findall(text)
    masked = text
    for i, token in enumerate(tokens):
        masked = masked.replace(token, f"__VAR_{i}__", 1)
    translated = translate_fn(masked)
    for i, token in enumerate(tokens):
        translated = translated.replace(f"__VAR_{i}__", token)
    return translated

def walk_and_translate(node, translate_fn):
    if isinstance(node, dict):
        return {k: walk_and_translate(v, translate_fn) for k, v in node.items()}
    if isinstance(node, list):
        return [walk_and_translate(item, translate_fn) for item in node]
    if isinstance(node, str):
        return translate_with_locked_vars(node, translate_fn)
    return node  # 布尔值、整数、浮点数和 None 原样返回

实操中容易忽略的三个边界问题

即便键名和 JSON 语法已经完全锁死,实际业务文件里还有三类内容需要你在脚本里提前过滤:

  • 枚举值与内部状态码: 商品或配置 JSON 里常混着机器读的枚举字符串(如 "status": "PUBLISHED"、"slug": "summer-sale")。建议在脚本里维护一个跳过键名集合(如 {"id", "status", "slug", "type", "url"}),命中这些键名时直接跳过不翻。
  • 内嵌 HTML 标签的词条: 如果 JSON 值里带有 "请点击 <a href='/login'>这里</a> 登录" 这样的富文本片段,回填后要检查 <a> 等标签的属性引号是否保持为合法转义。
  • ICU 复数与性别语法: 像 {count, plural, one {# item} other {# items}} 这种 ICU 格式,花括号里的 plural、one、other 是框架关键字,绝不能当成普通文本整段替换,只能拆分提取花括号内层的展示词条。

常见问题

意扣支持直接上传 .json 文件进行文档翻译吗?

不支持。意扣的文档翻译页面目前支持 PDF、DOCX、PPTX、XLSX、EPUB、HTML、TXT,以及字幕(SRT、VTT)、图片和录音录像文件。要用意扣翻译 JSON 词条,请先按上文方法一将字符串导出为 .xlsx 表格上传翻译,完成后再导回 JSON。

可以免费试用 JSON 转表格的翻译流程吗?

文中的 Python 转换与校验脚本完全开源免费;意扣新账号注册即送 200 积分,你可以先上传转换好的 .xlsx 词条表体验并排对照与去重效果,再决定是否购买积分包(详见价格与积分说明)。如果文档任务失败或取消,预扣的积分会自动退回余额。

怎么防止 JSON 里的数字、布尔值(true/false)被翻成字符串?

切记不要把 JSON 当作纯文本处理。使用 Python json.load() 解析后,布尔值、整数、浮点数和 null 会保持原生数据类型;无论是在递归脚本里只匹配 isinstance(node, str),还是在 XLSX 中转时把非字符串类型留在本地 keys_map.json 里,写回时都能保证原有数据类型丝毫不差。

参考资料