外文技术文档翻译实战：API手册/README整本转中文，代码块和图表排版一个不丢

前言

做开发的人，基本都逃不过读外文技术文档：API Reference、官方 README、白皮书、SDK 使用手册。文档动辄一两百页、或团队需要一份可分发的中文版时，翻译就成了刚需。

自己翻太慢，复制粘贴到网页翻译又快又乱——表格错位、代码块和正文混在一起、示意图位置丢失是家常便饭。这篇文章分享我处理这类需求的一套实战流程：用"版式保留"的在线 PDF 翻译把整本文档翻译成中文，再用脚本验证翻译后文档的结构完整性（页数、图片、可提取文本），保证交付物可分发、可检索。

环境准备

• 系统：Windows 10/11 或 Linux 均可
• Python 3.9+
• 依赖：pip install pdfplumber
• 一个支持格式保留的在线 PDF 翻译工具（本文以 PDFTranslator 为例：https://pdftranslator.org）

实现步骤

Step 1: 明确"格式保留"在技术文档里意味着什么

技术文档和论文不同，它的结构风险点更具体：

所以选翻译方案时，"能不能保住代码块和图表"比"翻得顺不顺"更重要——代码块的排版直接决定译文可不可用。

Step 2: 预处理——翻译前先拆分大文档

客户要的往往只是文档的一部分。一本 200 页的 SDK 手册，可能只有第 40-90 页和当前版本相关。我会先用 PDF 的拆分功能把目标章节抽出来再翻译，好处有三个：翻译更快、额度更省、交付物更聚焦。

以 PDFTranslator 内置的 PDF 工具箱为例，它自带拆分/合并/压缩功能，在同一个页面就能完成预处理，无需额外装软件。

Step 3: 执行版式保留翻译

把预处理后的 PDF 拖入 PDFTranslator，选目标语言（中英日韩法德西等 100+ 语言都支持），几分钟后下载译文。

关键点：不要用"复制粘贴"路线。技术文档的双栏/多栏排版一旦被复制成纯文本，结构信息就永久丢失了。版式保留翻译是在"版面"层面做的：表格还是表格，代码块还是代码块，图还在原来的位置。

实测一份 60 页的英文 API 手册转中文，PDFTranslator 约 3-5 分钟出结果，输出的 PDF 页数与原文一致，代码块缩进和表格结构基本完整，可直接在阅读器里复制代码。

Step 4: 用脚本验证译文结构完整性

翻译完成后我会跑一段校验脚本，用 pdfplumber 对比原文和译文的关键结构指标，避免"肉眼看着没问题、实际缺页漏图"。

import pdfplumber
from pathlib import Path

def check_structure(pdf_path: str) -> dict:
    """检查 PDF 的结构完整性指标

    Args:
        pdf_path: PDF 文件路径

    Returns:
        页数、可提取字符数、内嵌图片数
    """
    result = {"pages": 0, "chars": 0, "images": 0}
    with pdfplumber.open(pdf_path) as pdf:
        result["pages"] = len(pdf.pages)
        for page in pdf.pages:
            text = page.extract_text() or ""
            result["chars"] += len(text)
            # page.images 能拿到矢量图对象；嵌入位图也计入 page.objects
            result["images"] += len(page.images)
    return result

def verify_translation(src: str, tgt: str) -> None:
    """对比原文与译文的结构指标，输出校验报告"""
    s = check_structure(src)
    t = check_structure(tgt)
    print(f"页数:    原文 {s['pages']:<5} 译文 {t['pages']}")
    print(f"字符数:  原文 {s['chars']:<7} 译文 {t['chars']}")
    print(f"图片数:  原文 {s['images']:<5} 译文 {t['images']}")
    if t["pages"] != s["pages"]:
        print("[WARN] 页数不一致，请检查是否有缺页或串页")
    if t["images"] < s["images"] * 0.9:
        print("[WARN] 图片数量明显减少，请检查图表是否丢失")

if __name__ == "__main__":
    # 用法：python verify_pdf.py manual_en.pdf manual_zh.pdf
    import sys
    verify_translation(sys.argv[1], sys.argv[2])

运行示例输出：

$ python verify_pdf.py api_manual_en.pdf api_manual_zh.pdf
页数:    原文 60      译文 60
字符数:  原文 182340  译文 148211
图片数:  原文 42      译文 41

这个脚本的价值在于把"版式有没有丢"从主观感受变成可量化的检查项：页数一致说明没有整页丢失，图片数接近说明示意图基本保留；字符数变化是正常的（中文字符信息密度更高）。

Step 5: 交付前的三项人工抽检

脚本之外，我会人工抽检三处：

1. 代码块：随机打开译文第 1 章和第 5 章的各一段代码，复制出来看缩进和换行是否完整；
2. 表格：找一个参数较多的大表格，核对表头与行的对应关系；
3. 术语：API 方法名、类名这类标识符应保持原文不译，确认没有出现"翻译了函数名"的灾难。

总结

外文技术文档翻译，本质是**“结构迁移"而不是"文字替换”**。只要结构保住了——代码块能复制、表格能对齐、图片在对应章节——译文就是可用的交付物；结构一旦丢了，翻得再顺也是废纸。

我的完整流程可以概括为五步：

1. 评估：判断文档是否值得整本翻译、哪些章节需要翻译；
2. 拆分：用 PDF 工具箱抽出目标章节；
3. 翻译：用 PDFTranslator 这类版式保留工具整本翻译，支持 100+ 语言、免注册、每月 1000 页免费额度；
4. 校验：跑 pdfplumber 脚本核对页数/图片/文本，把结构检查量化；
5. 抽检：人工复核代码块、表格、术语三处关键位置。

如果你有更好的技术文档翻译工作流，欢迎评论区交流。

标签：PDF翻译、效率工具、文档处理、开发者工具