技术文档翻译指南：用翻译 API 处理 Markdown、代码块、链接与版本更新

技术文档翻译最重要的验收标准，是目标语言读者能否按照文档正确完成任务。译文需要准确表达前置条件、操作步骤和错误处理，同时保留可执行代码、参数名称、链接与版本限制。文章读起来顺畅，却让示例无法运行，仍然是不合格的文档。

用翻译 API 处理 Markdown 时，建议先解析文档结构，只提取允许翻译的文字，保护代码与稳定标识，再把译文还原到对应节点。完成后运行文档构建、链接检查和技术审校，最后按源版本发布。这样比整文件自由翻译更容易追踪错误和维护更新。

本文面向开发者文档、开源项目说明和帮助中心。示例说明一种结构化工作方式，不提供对所有 Markdown 方言通用的提取器，也不表示 TranslateHub 当前原生支持 Markdown、MDX 文件上传或自动发布。实际处理需要适配项目使用的解析器与构建工具。

一、技术文档翻译为什么必须关注“可执行性”？

一篇操作文档通常包含环境要求、命令、参数、预期结果和异常处理。这些元素彼此关联：前面要求某个版本，后面的示例就必须与该版本兼容；正文描述某个返回字段，响应示例也应该存在这个字段。

语言转换中最危险的错误，往往不是明显的不通顺，而是细小的语义漂移。例如，“仅在测试环境执行”变成“在环境中执行”，“不应重试”变成“应重试”，或者把一个可选参数描述为必需。它们会改变用户的操作判断。

因此，技术审校需要熟悉产品或接口的人参与。语言编辑可以改善表达，技术负责人则核对行为与边界。两者可以协作，但不能假定流畅度足以证明步骤正确。

一个简单的检查方法是从干净环境按照译文逐步执行，记录是否需要回到源语言文档才能完成操作。如果大量关键条件仍靠原文补充，说明译文的信息完整性需要改进，而不是只需要修饰措辞。

二、先盘点文档类型与 Markdown 方言

项目里的 .md 文件不一定具有相同语法。除了普通标题、段落与链接，还可能有表格、任务列表、提示块、自定义容器、模板变量或静态站点生成器的特殊写法。MDX 又可能包含组件和表达式，需要单独处理。

先列出实际使用的内容类型和构建链：README、API 参考、快速开始、故障排查、版本说明和产品教程，分别由谁维护，哪些需要多语言同步。不要因为扩展名相同就把所有文件套进同一条替换规则。

CommonMark 提供了常见 Markdown 结构的规范，但不能据此认定所有项目扩展都得到相同处理。开始提取前，应使用项目自己的解析配置读取代表性文件，确认代码块、引用、链接和 HTML 节点会如何表示。

对不支持的语法，宁可明确标记为待处理，也不要静默丢弃或转换。若提取工具忽略了一个警告容器里的正文，翻译文件虽然可以构建，用户却可能失去关键风险说明。

三、哪些内容可以翻译，哪些默认保护？

段落、标题、列表说明、表格中的自然语言和图片替代文本，通常属于可翻译内容。API 字段、函数名、命令行标志、文件路径、代码语法和 URL 则通常需要保留或按明确映射处理。

不能只根据“是不是英文”判断是否翻译。正文中的英文产品名可能需要保持不变，代码注释中的自然语言却可能适合翻译。应按节点类型与项目规则决定，避免同一词语在不同位置被机械替换。

默认保护代码，并不等于代码永远不能本地化。如果教程明确需要展示中文输入，或者代码注释为读者提供重要说明，可以安排单独任务。关键是改动经过规则和执行验证，而不是由整段翻译自动决定。

四、为什么建议使用语法树，而不是全文正则替换？

Markdown 同时包含块级结构与内联结构，链接、代码、转义和嵌套列表之间存在关系。全文替换很难判断同一段字符是普通文字、代码还是链接的一部分，容易在边界处破坏文件。

解析成语法树后，可以按节点类型选择文本，保留父子结构与属性。提取记录还可以保存文件路径、节点位置、源版本和文本摘要，方便后续把候选译文还原到对应位置。

{
  "documentId": "quick-start",
  "sourceRevision": "docs-42",
  "nodeId": "intro.paragraph-2",
  "nodeType": "paragraph",
  "sourceText": "创建 API Key 后，在服务端发送请求。",
  "targetLocale": "en"
}

这是应用侧任务记录示例，不是翻译接口参数。nodeId 的设计也不能只依赖当前行号，因为新增段落会让位置变化；可以结合稳定内容标识、结构路径和源版本进行匹配，并在冲突时要求人工确认。

语法树方案仍需要验证序列化结果。部分工具还原 Markdown 时可能改变列表缩进、引用样式或表格排版。要区分仅格式变化和实际语义变化，避免审校者被大量无关差异淹没。

五、代码块保护：命令、参数与示例输出分开处理

代码围栏内部默认不进入普通翻译任务，语言标记、缩进与特殊字符都应保留。下面示例中，正文可以本地化，命令和参数保持不变；译文不能把 target_lang 改成自然语言名称。

## 发送第一次请求

在服务端设置密钥后执行以下命令。

```bash
curl --request POST 'https://api.deeplvip.com/api/v1/translate' \
  --header "Authorization: Bearer ${TRANSLATEHUB_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"text":"Hello","target_lang":"zh-Hans"}'
```

命令示例还要避免误用真实密钥、内部域名和敏感样本。翻译任务通常不需要知道生产凭证；文档中的占位符应保持明确，让读者知道哪些值需要自行替换。

示例响应和测试断言具有额外约束。若正文引用响应里的 engine 字段，译文应保留字段名；若某个输出是程序精确返回的错误码，也不能为了易读而直接改写。可以在代码块外解释其含义。

代码注释是否翻译，应按项目统一规则处理。需要翻译时，可以只提取注释文本，并在还原后重新检查代码。对嵌有注释语法、字符串模板或多语言代码的文档，不要用一个粗糙正则覆盖所有情况。

六、链接本地化：翻译显示文字，谨慎映射目标地址

一个 Markdown 链接至少涉及显示文字和目标地址，目标还可能有查询参数与片段锚点。通常可以翻译显示文字，但地址需要检查目标语言是否真的存在对应文档，不能简单给所有 URL 增加 /en/。

项目可以维护显式页面映射，例如中文快速开始对应英文快速开始，中文故障排查若没有译文，则保留原链接并让界面清楚表达语言范围。不要把不存在的深层文档随意改成目标语言首页，读者会失去原本需要的信息。

相对链接需要以源文件所在位置解析，再映射到发布路径。文件目录、语言目录和构建 URL 并不总是一一对应，尤其是静态站点会把 README、索引文件或路由配置转换成不同地址。

查询参数也应保持用途明确。语言切换不能误删版本选择、代码示例参数或外部站点必要信息。对外链，默认保持原地址；只有文档维护规则明确提供本地化版本时才替换。

Google 的链接最佳实践强调使用可识别的链接和有意义的锚文本。对文档读者而言，这也意味着“查看错误处理说明”通常比多个模糊的“点击这里”更容易理解和定位。

七、标题翻译之后，页内锚点也需要检查

许多文档系统根据标题自动生成片段 ID。标题从中文变成英文后，原先指向中文标题的页内链接可能不再有效。页面主体翻译完成，却留下失效目录，是很常见的漏项。

可以在构建时读取最终标题与生成 ID，检查所有页内引用和跨页片段链接。如果框架支持显式稳定锚点，也可以为长期被引用的章节设置固定标识，但要遵循项目语法，不能假定任意 Markdown 渲染器都支持同一种写法。

标题结构还应该保持信息关系。一个步骤属于上一节的子操作，不应因为译文改写就变成同级章节。提取和还原时保留标题层级，语言编辑只调整可见标题，技术负责人再确认导航逻辑。

文档章节迁移时，检查站内引用、外部常用入口和旧链接兼容策略。稳定路径与锚点是读者书签、工单和社区回答的一部分，不能只根据当前页面是否能打开判断迁移成功。

八、Frontmatter、表格与提示块如何处理？

Frontmatter 里可能有标题、摘要、作者、分类、路由、版本和草稿状态。应按字段设置策略：可见标题和摘要可以翻译，日期与版本保持可信源值，路由和技术配置按项目规则处理。

title: 创建第一个工作空间
description: 完成初始化并邀请团队成员。
productVersion: v2
draft: false

在这个示例中，标题与描述可以生成候选译文，productVersion 和 draft 不应由翻译工具重新判断。还原时使用 YAML 解析与序列化工具，避免冒号、引号和换行导致元数据失效。

表格中的列名和解释通常需要翻译，参数名、类型和默认值则通常保护。长译文可能改变可读性，尤其在手机上，应检查横向滚动和表头关联，必要时重组说明而不是删掉重要条件。

提示块中的“注意”“警告”“已弃用”等级也具有技术含义。可以本地化标签显示，但不能改变警告级别或隐藏弃用信息。自定义容器与组件属性要由解析器保护，避免翻译后的标签不再被构建工具识别。

九、用翻译 API 建立文档任务流水线

一个实用流程是先固定源提交或文档版本，再解析并提取节点；对新增与变化内容创建目标语言任务；生成候选译文后还原文件；最后执行构建、结构检查与技术审核。

TranslateHub 当前公开文本接口使用单段 text 和 target_lang，具体字段见开发者文档。语法解析、节点对应、任务 ID、文件还原和审校门槛由你的应用流程负责，不应当作接口自动提供的能力。

任务记录保留源提交、文件路径、节点标识、目标语言、策略版本和状态。接口调用失败只重做对应任务；还原失败则先检查结构或版本冲突，不必立刻重新消耗上游翻译量。

对于大量节点，使用受控并发与持久化状态。不要在一次构建进程中依赖内存保存数小时进度，也不要让页面访问临时触发整篇文档翻译。执行策略可参考批量翻译 API 成本优化指南。

十、术语表要连接代码、界面和技术说明

文档术语不能脱离产品界面。例如，界面按钮已使用某个译法，教程却用另一个近义词，读者可能找不到对应操作。建议把公开功能名、界面标签和文档术语放在共同管理规则下。

API 名称、参数与类型需要保留准确拼写。可以在自然语言中解释其含义，但不要把代码标识符改成目标语言词汇。产品概念与代码命名不一致时，也应明确说明映射关系，而不是让翻译人员自行猜测。

同一词语可能具有不同技术意义，例如“实例”“会话”“令牌”和“流”。术语表要记录定义、适用模块和例句，避免全局强制替换造成新错误。对弃用名称也可以保留历史别名，帮助读者理解旧版本资料。

审校中发现反复误译时，先判断是术语定义缺失、上下文不足，还是源文不准确。改进源文和规则通常比逐页修补更可持续。选型与评测方法可结合翻译 API 选型指南使用。

十一、原文更新后，如何实施增量翻译？

用固定源提交或内容版本作为翻译基线，比依赖“上次修改日期”更可靠。一次更新可以识别新增节点、修改节点、删除章节与移动内容，再为需要更新的目标语言建立任务。

内容移动不一定意味着重新翻译，但语境发生变化时仍需复核。例如同一句警告被移到不同功能说明中，原有译文可能不再合适。复用判断要同时考虑文本、上下文和产品版本。

删除的源章节也需要同步处理。不能只持续添加译文，却让旧语言页面长期保留已弃用步骤。若决定保留历史文档，应明确版本入口和维护状态，而不是让用户误以为它适用于当前产品。

新结果写回前，再次检查源基线是否变化。旧任务可以作为历史候选保留，但不能覆盖更新后的文档。审校者也应看到源差异，避免在一个过时版本上投入大量修改后才发现需要重做。

十二、怎样设计技术审校，让语言与行为都准确？

建议分为内容完整性、术语与表达、操作验证三部分。完整性检查是否遗漏条件、例外和错误处理；语言检查是否自然明确；操作验证则依据目标语言文档完成真实任务。

测试样本应包含成功路径和失败路径。例如密钥缺失、参数不合法或目标资源不存在时，文档有没有说明下一步；错误提示是否与实际接口一致；重试建议是否符合服务行为。只验证正常请求，容易漏掉真正需要帮助的情境。

示例执行应在受控测试环境中进行，使用测试凭证和非敏感数据。对可能修改资源的命令，先确认测试范围与清理方式。代码片段来自文档，并不代表可以不经判断在生产环境运行。

审校记录保存问题类型和节点位置，而不只是“通过”或“不通过”。多次出现同一术语错误，应修正规则；多次出现链接失效，应改进构建校验。这样下一批文档可以减少重复问题。

十三、发布前检查：文件能构建，还要链接和内容可用

文档构建通过是重要门槛，但不是全部。构建器可能允许不存在的目标地址，也可能不会检查代码是否能执行。因此应根据项目规模补充链接、锚点、资源文件和关键示例验证。

检查最终页面，而不只检查源 Markdown。图像路径、代码高亮、表格宽度和提示块样式可能在构建后才出现问题。多语言布局也要看移动端，避免长标题或参数表溢出可视区域。

可以使用下面的发布清单：

• 文档标题、摘要和正文属于同一目标语言。
• 代码、参数、文件路径和变量按规则完整保留。
• 关键操作步骤与当前产品版本一致。
• 所有本地资源、文档链接与页内锚点有效。
• 未翻译页面没有伪造目标语言入口。
• Frontmatter、表格和提示块能够正确渲染。
• 批准记录与源提交绑定，旧任务不能覆盖新版本。
• 公开页面可访问，存在回滚和问题反馈入口。

十四、技术文档 SEO 应围绕真实操作问题

文档最有价值的搜索入口往往是具体任务和错误，例如如何创建密钥、为什么出现某个状态、某个参数如何使用。标题与首段应准确说明文档解决什么问题，再给出条件与步骤，不必为了关键词增加大段泛泛背景。

一篇“如何处理翻译接口限流”的页面，应尽早说明如何判断错误、等待和重试，而不是先重复介绍所有翻译产品能力。文档内容的深度来自能否让读者完成任务，不来自机械重复接口名称。

公开语言版本需要稳定 URL、完整正文和真实的对应关系。技术文档之间的链接应该帮助读者继续任务，例如快速开始连接鉴权说明，错误处理连接配额说明。与主题无关的密集内链会增加干扰。

不要为每个近义表达生成几乎相同的教程，也不要发布只有默认语言正文的目标语言页面。对于维护能力有限的团队，优先翻译核心入口与高频问题，并保持更新，通常比一次铺开大量无人负责的版本更可执行。

十五、小团队如何启动一个文档翻译试点？

可以选择一篇快速开始、一篇 API 参考和一篇故障排查，覆盖不同结构。先明确解析规则与保护范围，再生成一个目标语言的候选版本；记录哪些节点需要人工判断，哪些能够自动校验。

下一步让技术人员完全依据译文完成操作，检查是否需要回看原文。把问题归类后修正源文、术语或工具，再进入小范围发布。这个过程比直接全量翻译更容易形成可靠规则。

当试点能够从源更新走到增量任务、审校、构建和回滚，再扩大文件数量与语言范围。如果审核积压已经很高，应先调整范围和流程，避免新增语言长期落后。

整个项目至少要回答三个问题：当前译文对应哪个源版本？谁批准了关键操作说明？发现错误时如何快速恢复？这些问题有明确答案，才算建立了可维护的文档本地化能力。

十六、技术文档与 Markdown 翻译常见问题

Markdown 可以当普通文本直接翻译吗？

简单内容可以用于初步验证，但正式流程需要保护代码、链接、元数据和特殊语法。整文件翻译的结果即使看起来正常，也应经过构建、结构与技术审核。复杂项目优先按语法结构提取。

代码注释应该翻译吗？

按项目规则决定。解释性注释可能需要本地化，参数名、字符串约定和程序依赖内容则要保护。需要修改注释时，应单独处理并重新验证代码，而不是开放整个代码块自由改写。

翻译标题后，原来的页内链接还能用吗？

如果锚点由标题自动生成，可能发生变化。应检查最终渲染的 ID 并更新引用，或使用框架支持的显式稳定锚点。不能只验证页面返回成功就认定片段链接也有效。

源文只改了一个词，需要重译整篇文档吗？

通常可以按节点或内容块增量处理，但需要判断语境、术语和产品版本是否改变。修改关键条件可能影响多个章节，纯格式变化则未必需要新的翻译请求。差异识别与审核应协同决定范围。

MDX 能和普通 Markdown 共用提取规则吗？

不能默认这样处理。MDX 可能包含组件、属性和表达式，应使用相应解析器并只选择明确允许翻译的节点。不要为了提取内容执行不受信任的表达式或脚本。

多语言文档上线后，需要持续维护吗？

需要。接口字段、产品行为和推荐步骤都可能更新。通过源版本绑定、增量任务和明确负责人，可以识别过时内容；没有维护能力的历史版本，应清晰标示适用范围或按项目策略归档。

参考资料与实施边界

本文于 2026 年 10 月 21 日整理。文中流程、任务记录和代码片段用于说明实现思路，需与实际 Markdown 方言、构建工具和接口版本适配。主题插画为 AI 生成，流程图为本地绘制。

• CommonMark 0.31.2 规范：常见 Markdown 结构定义。
• Google：链接最佳实践。
• TranslateHub 开发者文档。
• 持续本地化 CI/CD 工作流。
• SaaS JSON 语言包翻译指南。
• 跨境电商商品翻译指南。