Google Cloud Translation API翻译HTML语法错误的原因及解决方法

问题背景 #

• 运行环境：Node.js
• 调用服务：Google Cloud Translation API
• 业务场景：批量翻译数据库中存储的HTML格式博客文章，目标覆盖约20种语言
• 异常表现：翻译完成输出的HTML存在多处无规律语法错误

核心诱因 #

1. API调用参数配置错误
   若请求时未显式指定format参数，API会默认按纯文本模式处理内容，会将HTML标签、标签属性、实体字符全部纳入翻译范围，直接造成标签缺失、属性值被翻译、引号/尖括号位置错位等问题，是这类故障最常见的原因。
2. 内容拆分逻辑破坏DOM上下文
   若为了规避API请求长度限制，将完整HTML按句子、字数硬拆分为过小的碎片逐段请求，API无法感知完整DOM树结构，很容易在碎片边界处出现标签遗漏、闭合错位的问题——比如上一个碎片末尾的开标签，会在下一个碎片的翻译过程中被判定为冗余内容删除。
3. 特殊字符转义逻辑不统一
   翻译前后未做统一的HTML实体转义/反转义处理，原文中的 、<、>、引号等实体字符，会在翻译过程中被转为普通字符或被重复转义，直接导致标签语法失效。
4. 复杂结构解析偏差
   若博客HTML包含多层嵌套标签、内联代码、自定义短代码、非标准属性，API内置的HTML解析器对这类复杂、非标准结构的识别准确率会明显下降，容易出现标签截断、属性值拆分翻译的问题。

可落地解决方案 #

• 修正API请求参数：所有翻译请求必须携带format: 'html'参数，同时指定model: 'nmt'调用谷歌神经翻译模型，该模型针对结构化HTML做过专项优化，会自动跳过标签、标准属性等非可见文本内容，仅翻译用户可见的文本节点。
• 按DOM节点拆分长内容：如果单篇内容长度超过API限制，不要按字数硬拆分，使用Node端成熟的DOM解析库（如cheerio、htmlparser2）先将完整HTML解析为DOM树，以完整开闭的块级节点为最小拆分单元，绝对不要把单个标签拆分到两个不同的翻译请求中。
• 前置提取非翻译内容：对于HTML中的代码块、嵌入组件、自定义短代码、固定跳转链接等不需要翻译的内容，提前提取后替换为{{custom_placeholder_x}}格式的无意义占位符，等全文翻译完成后，再将占位符替换回原始内容，从根源避免这类内容被误修改。
• 统一转义与后置校验流程：翻译前对文本节点内的特殊字符做标准HTML实体转义，拿到翻译结果后先做反转义，再通过DOM解析库重新解析渲染一次输出，自动修复轻微的标签不闭合、位置错位问题。
• 小语种结果抽样校验：针对20种目标语言中的小语种做抽样人工校验，若特定语种频繁出现结构错误，可适当调小单请求的内容长度，降低模型解析压力。

内容的提问来源于stack exchange，提问作者Pedro Cristovão