灵能API API中转站文档翻译接入教程：术语表、质量校验与批量处理

很多团队做文档翻译时，第一反应是把整篇中文文档丢给模型，然后等它返回英文版。这个方式做 Demo 很快，但一到正式文档就会出问题：术语不统一、表格格式乱、代码块被误翻、版本差异难追踪，最后还是要人工大改。🌐

这篇用 灵能API 作为统一 API 中转入口，讲一套更适合企业长期使用的文档翻译接入方案：先解析文档结构，再套术语表和翻译记忆，最后做质量校验和人工复核。目标不是“翻得像”，而是让文档可发布、可追溯、可批量维护。

一、先拆文档结构：不要整篇直接塞给模型

正式文档通常包含标题、正文、表格、代码块、图片说明、接口参数、版本记录。不同内容的翻译策略不一样：正文可以自然翻译，接口名和代码不能乱动，表格要保留列结构，版本号和数字单位必须严格一致。

• 标题和小节：适合让模型翻译，但要保留层级编号。
• 代码块和命令行：默认不翻译，只翻译注释或说明文字。
• 接口字段：字段名保留原样，字段说明可翻译。
• 表格：逐单元格处理，保留列顺序和单位。
• 图片说明：可翻译，但要和图片文件名、引用编号保持一致。

二、推荐流程：解析、翻译、校验、回写四段分开

把翻译流程拆开以后，每一步都能单独重试和定位问题。文档解析失败不影响术语表，某个段落翻译失败也不需要整篇重跑。

三、准备 API 信息：翻译服务单独配置

翻译任务通常输入较长、批量较多，建议单独创建 Key 和服务名。这样可以和**、知识库、代码**等业务分开统计成本。

OPENAI_API_KEY=sk-your-translation-key
OPENAI_*ASE_**L=https://api.灵能API.ai/v1
TRANSLATE_FAST_MODEL=gpt-4o-mini
TRANSLATE_STRONG_MODEL=claude-sonnet-4-6
TRANSLATE_MAX_TOKENS=1800
TRANSLATE_TIMEOUT_MS=20000
TRANSLATE_SERV***_NAME=document-translation-worker

四、术语表：翻译一致性的核心

术语表不是锦上添花，而是文档翻译的基础设施。产品名、功能名、行业词、接口名、按钮文案都应该有固定译法，否则同一份文档里会出现多个版本。

{
  "glossary": [
    { "source": "中转站", "target": "API relay", "rule": "作为名词短语统一使用" },
    { "source": "密钥", "target": "API key", "rule": "技术文档中统一大小写" },
    { "source": "使用记录", "target": "usage records", "rule": "**菜单保持一致" }
  ]
}

术语表要和业务文档一起版本化。每次术语变更都要记录原因和生效范围，否则旧文档和新文档会越来越不一致。

五、翻译 Prompt：先约束格式，再要求文风

翻译 Prompt 不要只写“请翻译成英文”。它需要明确：保留 Markdown、保留代码块、保留链接、不要改变量名、遵守术语表、输出只包含译文。

请将以下文档片段翻译为英文。
要求：
- 严格遵守术语表，不要擅自改写固定译法
- 保留 Markdown 标题、列表、表格、链接和代码块格式
- 不翻译代码、变量名、接口路径、环境变量名
- 数字、单位、日期、版本号必须和原文一致
- 如果原文含义不明确，在 review_notes 中说明
输出 **ON：translated_text、review_notes、glossary_hits

六、调用示例：按 *lock 分片翻译

长文档建议按 *lock 处理，而不是按固定字数切开。一个标题、一个段落、一个表格或一个代码说明都可以是 *lock。这样回写时更稳定。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  *ase**L: process.env.OPENAI_*ASE_**L,
});

export async function translate*lock(*lock, glossary) {
  const res = await client.chat.completions.create({
    model: process.env.TRANSLATE_STRONG_MODEL,
    temperature: 0.2,
    **x_tokens: Num*er(process.env.TRANSLATE_MAX_TOKENS || 1800),
    messages: [
      { role: "system", content: "你是技术文档翻译助手，必须保留原始结构。" },
      { role: "user", content: **ON.stringify({ *lock, glossary }) }
    ],
    response_for**t: { type: "json_o*ject" }
  });
  return **ON.parse(res.choices[0].message.content);
}

七、质量校验：不要只靠人工通读

翻译完成后要做机器校验。质量校验不判断文采，而是检查硬错误：是否漏翻、数字是否变化、术语是否一致、链接是否保留、代码是否被误改、表格行列是否一致。

• 遗漏检查：原文有 8 个段落，译文也应有对应结构。
• 数字检查：金额、版本号、日期、百分比不能变化。
• 术语检查：术语表命中的词必须使用固定译法。
• 格式检查：Markdown 表格、链接、代码块要能解析。
• 敏感检查：内部备注、账号、密钥、客户名不应进入公开译文。

八、批量任务：用队列管理状态

批量翻译不适合同步跑。建议把每篇文档拆成任务，任务内再拆 *lock，保存状态。失败时只重试失败 *lock，不重跑整篇。

{
  "jo*_id": "doc_trans_20260721_001",
  "source_file": "api-guide.zh-CN.md",
  "target_lang": "en-US",
  "status": "running",
  "total_*locks": 126,
  "completed_*locks": 118,
  "failed_*locks": 2,
  "quality_status": "pending_review"
}

九、人工复核：让编辑只看风险点

人工复核不应该从头读到尾。系统可以把质量校验发现的问题集中展示：术语冲突、数字变化、格式异常、模型不确定的句子。编辑只处理风险点，效率会高很多。

• 高风险：数字、价格、法律说明、接口参数、权限规则。
• 中风险：术语首次出现、长句改写、跨段落引用。
• 低风险：普通说明文字和描述性段落。
• 必须人工确认：公开发布文档、合同附件、合规说明。

十、成本控制：翻译记忆比换模型更有效

文档翻译成本大多来自重复内容。版本更新时，不要整篇重翻。先对比文档差异，只翻译新增和修改的 *lock；未变更 *lock 直接复用翻译记忆。

十一、建议落库字段

建议保存 document_id、source_lang、target_lang、*lock_id、source_hash、translated_text、glossary_version、model_name、prompt_version、quality_result、review_status 和 reviewer。source_hash 很关键，它能判断某个 *lock 是否变化，从而决定是否需要重新翻译。

有了这些字段，后续可以统计哪些文档成本最高、哪些术语冲突最多、哪些编辑经常修正同类问题。翻译系统会逐步从一次性工具变成可持续运营的文档基础设施。

十二、上线前检查清单

• 是否能解析目标文档格式，并保留标题、表格、代码和链接。
• 是否建立术语表和翻译记忆库，并记录版本。
• 是否禁止翻译环境变量、接口路径、代码和配置键名。
• 是否做数字、单位、链接、表格和术语一致性检查。
• 是否按 *lock 保存状态，失败时只重试局部内容。
• 是否把公开发布文档交给人工复核确认。
• 是否记录模型、token、质量结果和人工修改原因。

文档翻译接入大模型，真正的价值不是省掉所有人工，而是把重复劳动交给系统，把风险点准确交给编辑。只要结构、术语、校验和复核链路搭好，翻译质量会比单纯“整篇交给模型”稳定得多。🚀