译格 PDF Studio：从零做一个保版式的本地 PDF 翻译工作台

整体设计#

技术栈刻意保持简单：后端 FastAPI，前端原生 HTML/CSS/JavaScript（PDF 渲染用 pdf.js），翻译版式重建交给 PDFMathTranslate / pdf2zh / BabelDOC。

翻译后端支持三种模式：

• OpenAI-compatible 网关：接 DeepSeek 等任意兼容 API，走 pdf2zh 的 openailiked 服务
• Argos 离线翻译：开源 NMT，完全无需 API Key
• Mock 版式测试：不翻译只复制原 PDF，用来验证界面和任务流程

后台任务架构#

长 PDF 翻译动辄几分钟，同步 HTTP 请求必超时。所以翻译接口做成了任务模式：

1
POST /api/translate        → 创建任务，返回 job_id / status_url / download_url
2
GET  /api/jobs/{job_id}    → 查询状态：queued / running / succeeded / failed
3
GET  /api/preview/{job_id} → 内嵌预览译文 PDF
4
GET  /api/files/{job_id}   → 下载译文 PDF

前端轮询任务状态，succeeded 后才加载右侧 PDF；失败时展示 pdf2zh/BabelDOC 的错误摘要，方便定位是版式解析还是翻译服务的问题。

结构化翻译知识库：这个项目最核心的部分#

术语一致性是机器翻译落地的老大难。译格的解法是一套结构化知识库，存服务端 JSON，可保存多套、随文档类型切换：

1
{
2
  "name": "计算机与AI",
3
  "glossary": [
4
    { "src": "large language model", "dst": "大语言模型",
5
      "domain": "AI", "status": "preferred", "case_sensitive": false }
6
  ],
7
  "style_rules": ["使用准确、简洁的技术中文"],
8
  "do_not_translate": ["代码", "命令", "公式"]
9
}

几个关键设计：

• 术语状态机：每条术语有 preferred（推荐）/ forbidden（禁译）/ deprecated（弃用）状态，forbidden 的术语自动作为”保留原文”注入
• 按需注入：翻译时只把实际出现在文档中的术语注入提示词，不浪费上下文，命中数会体现在质检报告里
• 翻译记忆（TM）：知识库可存历史句对，原文命中时作为”参考译法”注入，保持跨文档一致
• 专业格式互通：支持 CSV / TBX（术语库）/ TMX（翻译记忆）导入导出，可以直接对接 SDL Trados、OmegaT 这些专业 CAT 工具
• 内置一套自建的”计算机与AI”领域种子术语库，无第三方版权问题

MCP 术语检索与 Claude Skill#

两个偏工程化的扩展：

MCP 术语服务：项目内置一个术语 MCP Server，翻译前实时检索术语；服务不可用时自动回退到本地知识库，属于”有则更好、无则不挡路”的设计。

Claude Skill 封装：.claude/skills/translate-pdf/ 把整条翻译流水线封装成可被 Claude Code 调度的 skill——AI 编程助手可以直接指挥这个工作台干活。

翻译质量的细节工程#

• 文档级上下文：自动抽取标题、摘要和高频术语注入提示词，让模型知道自己在翻译什么领域的文档
• 文档类型策略：按类型（学术论文/技术文档/合同/通用）配置”保留原文”段落——目录、参考文献、附录这类整页内容自动检测页码保留；摘要、公式、代码走提示词禁译
• 跨页连续性：自动识别页尾到下页页首的断句上下文，减少长句被硬切导致的逻辑断裂
• 质量检查：翻译完成后扫描未解析占位符、乱码字符和替换字符
• 异常页回退：个别页翻译异常时自动用 legacy 引擎重跑并替换回最终 PDF
• 并发可调：质量/均衡/速度三档（4/8/16 线程）或直接指定 1–32 线程，长文档提速明显，同时提示注意翻译服务商限流

总结#

这个项目串起了一条完整的工程链路：FastAPI 后台任务、pdf.js 双栏联动、版式重建工具链的整合调优、术语知识库的数据结构设计、与专业翻译行业标准（TBX/TMX/CAT）的互通，以及 MCP 和 Claude Skill 这类新式 AI 工程接口。它解决的是我自己每天都会遇到的真实问题——这也是我判断一个 side project 值不值得做的标准。