如何翻译技术文档而不破坏代码

技术文档是严格的：一个破损的代码围栏、占位符或锚点可能会导致构建失败、读者困惑或复制粘贴失败。本指南为您提供了一种可重复的、安全的工作流程，以自信地翻译技术文档，同时保持代码完整和文档可发布。

适用对象：技术作家、开发者倡导者和从事开发者文档、API指南和README风格内容的翻译人员。

概览：

理解哪些内容绝对不能翻译（代码、密钥、令牌）
保留工具解析的语法（围栏、大括号、锚点）
在编辑后验证结构化数据和链接
使用自动化工具在发布前捕捉问题

翻译前准备

清点内容类型

Markdown（标题、链接、表格）、代码块、内联代码
结构化数据：JSON/YAML/TOML片段和配置文件
截图、图表和嵌入的视觉内容

定义不可翻译的标记

文件路径、包名、导入、API名称、CLI标志、环境变量
占位符和变量：{count}、%s、$HOME、{{token}}
文件名和扩展名：config.yaml、.env、.md、.json

建立一致性保护措施

术语表/术语库用于领域术语和产品名称
风格指南：语气、正式程度、标点符号、大小写、标题规则
每个语言环境的锚点/slug策略（稳定版与本地化版）

设置安全验证

预发布构建以在每批次后验证Markdown/链接
JSON/YAML/TOML的解析器/语法检查器
CI中的链接检查器和锚点验证器

核心保障

不要翻译代码、标识符、密钥、文件名、环境变量或标志。
保留工具解析的标点和语法（反引号、大括号、管道符）。
保持重要的空白：代码和列表结构的缩进。
使用带语言标签的围栏代码块一致性（js, bash等）。
更倾向于使用翻译者注释而不是“修复”代码逻辑——而是向维护者标记问题。

代码块和内联代码

保持代码块、语言提示和内容不变。仅在需要时翻译注释和人类可读字符串。

示例——安全与不安全：

// SAFE: 仅注释被本地化
// 获取用户令牌
import { getToken } from "@acme/sdk";
const token = await getToken();

// UNSAFE: 不要翻译标识符/导入/包名称
// import { obtenirJeton } from "@acme/sdk"; // ❌

内联代码必须保持原样：

好的: “运行 npm install -g acme-cli 然后 acme login。”
不好: “运行 npm install -g acme-cli 然后 acme connexion。” ❌

验证复制粘贴性：如果读者复制任何代码片段，它应该像源代码一样运行。

占位符和ICU消息格式

准确保留占位符，包括周围的空格和标点。

# 不要改变标记或空格
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ 在大括号内添加空格

ICU示例：

{count, plural,
  =0 {No messages}
  one {# message}
  other {# messages}
}

不要更改键（count、one、other）。
仅翻译人类可读部分（“message”、“messages”）。
未经产品指导，不要引入或移除复数类别。

链接、锚点和短名称

保持Markdown链接语法和解析策略一致。

[阅读API指南](/api/getting-started)  
[查看配置部分](#configuration)

如有需要，翻译链接文本；对URL和锚点保持谨慎。
锚点：保持各语言间稳定锚点或生成每个语言的锚点并相应更新引用。
验证相对路径和哈希锚点在翻译后仍然有效。
不要翻译文件扩展名或查询参数。

结构化数据（JSON/YAML/TOML）

仅翻译值——永远不要翻译键、类型或结构。编辑后始终重新解析。

JSON:

{
  "title": "用户指南",
  "cta": "开始使用",
  "limits": { "max": 5, "unit": "requests/second" }
}

像 title、cta、limits、max 这样的键必须保持不变。
数字、布尔值和空值保持为类型，而不是文字。

YAML（注意折叠标量）：

note: >
  行被折叠成一个段落。
  保持缩进和标记不变。

保持引用、转义、缩进和尾随逗号（如适用）。

文件名、CLI 和 API 名称

不要翻译文件名、包名、端点或 CLI 标志。
保持大小写敏感性与源文件完全一致（例如，--DryRun vs --dry-run）。
保持命令逐字不变；如果存在特定于语言环境的差异，请添加说明。

# 正确
kubectl get pods --namespace default

# 错误（标志被翻译） ❌
kubectl get pods --nom-espace defaut

Markdown 注意事项

表格：保持管道和对齐；不要打破列。

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

警告/注释：保留工具使用的标记。
内联 HTML：避免触碰标签/属性。
脚注：保持 ID 和顺序。
智能引号：在代码上下文中更喜欢直引号。

视觉和可访问性

本地化替代文本以表达意义，而不是像素内容。
优先使用与语言环境无关的截图（突出显示 UI 而不是语言），或提供每个语言环境的集合。
保持图表源文件（例如，Mermaid）在各语言环境中同步。
避免在图像中嵌入文本；将标题和标签外部化。

SEO 和元数据

使用适合语言环境的关键词翻译标题、描述和标题。
保持规范 URL 和 hreflang 与网站规则一致。
不要翻译 meta/property 键或 JSON‑LD 键。
将别名与您的锚点策略对齐，以避免 404 错误。

工作流程和自动化

使用保留代码范围和标签的 CAT/LLM 工作流程。
使用术语表和不翻译列表锁定术语。
添加 pre-commit hooks 来检查 Markdown 和验证 JSON/YAML。
在每个 PR 上运行链接检查器和锚点验证器。
将更改批量处理为小的、可审查的块，并跟踪差异。

建议的工具（根据您的技术栈进行调整）：

CI 中的 Markdown 检查和链接检查
JSON/YAML 解析步骤以捕获语法回归
正则表达式包用于扫描占位符和数字格式

QA 和验证

在合并之前运行这些检查：

构建站点以捕获语法问题：pnpm build
类型/内容检查（Astro 内容集合）：pnpm astro check
预览和重点测试关键页面：pnpm preview
验证代码示例是否编译或运行（如适用）
运行链接和锚点检查器；修复任何 404 或损坏的哈希

常见陷阱

意外翻译键/占位符。
破坏代码围栏或表格管道。
本地化文件路径、标志或 API 名称。
更改标题而不更新锚链接。
在代码或 JSON 中引入智能引号。

附录：快速检查清单

预检（5 项）

术语表和不翻译列表准备好
令牌/占位符已定义并受到保护
锚点/slug 策略已确认
链接目标已映射（内部 vs 外部）
可用的暂存构建

代码示例安全性（5 项）

围栏和语言提示完好
标识符/导入未触动；仅本地化注释
占位符和引号保留
复制粘贴测试通过
过时的代码片段标记给维护者

结构化数据（5 项）

键和值类型未触动
引号/转义/缩进保留
数字和布尔值保持为类型
本地解析器/检查器通过
差异已审查以防止意外键更改