英文技术书并不是读不懂但读完整本通常还是比母语慢。这件事很容易被低估。平时查一段文档、看一个 Stack Overflow 回答英语不会构成明显障碍可当阅读变成几百页的长期任务持续的语言切换会占掉不少注意力。我们做Translate Technical Books最初只是想解决这个朴素的问题能不能把自己有权处理的英文技术书稳定地转成真正适合阅读的中文版本项目地址https://github.com/cfodes/translate-technical-books直接让模型翻译 PDF为什么不够第一次尝试的人很自然会想到提取 PDF 文本翻译再合并。普通文章也许可以这样做技术书却很容易出问题。代码、命令行输出、公式、表格和图片都依赖结构PDF 提取到的字符顺序不一定就是人的阅读顺序代码围栏、图注关系和标题层级也可能已经丢失。更麻烦的是模型会努力把损坏的输入翻译成“看起来正常”的中文。如果缺了一个参数、断了一行公式成品未必会主动提醒你。因此这个项目把工作分成了两步。第一步不是翻译而是得到可信源稿translate-technical-book-parser-first负责解析 PDF。它会比较 Marker、Docling 与 PyMuPDF4LLM 的结果并在出现分歧时回到原 PDF 页面寻找证据。只有结构、哈希和页覆盖检查通过才会得到后续使用的 canonical Markdown。如果输入本身就是结构良好的 Markdown 或 EPUB这一步可以简单很多主要由本地确定性脚本完成。第二步才是翻译translate-technical-book把已经通过检查的 Markdown 按结构切分。代码、公式、API、路径、链接和图片引用会被保护每个分块翻译后单独检查再合并成整本书。这样设计不是为了把流程搞复杂而是为了让它可以中断续跑也可以只重试失败的部分。一本几百页的书不应该因为最后一个章节出错就从头再来一次。最终保留中文 Markdown 作为可编辑主版本需要时再构建 EPUB、HTML 或 PDF。我们已经跑过哪些规模开发期间我们用三个匿名的完整技术书样本验证了整套流程共 679 个翻译分块最终自动 QA 为 679/679。为了方便比较README 使用 2026-08-10 的gpt-5.6-terra价格重新折算三个样本的 Standard 干净载荷等价成本分别约为 5.60、5.76 和 10.87 美元Batch/Flex 约为一半。这些不是历史实际账单。真实 agent 运行还会包含工具回显、失败重试和重复上下文。一个保存了完整日志的样本Token 是干净载荷的 3.27 倍。仓库里保留了完整的计算口径方便复算也避免用一个过于漂亮的数字误导使用者。如何安装gitclone gitgithub.com:cfodes/translate-technical-books.gitcdtranslate-technical-booksCODEX_SKILLS_DIR${CODEX_HOME:-$HOME/.codex}/skillsmkdir-p$CODEX_SKILLS_DIRcp-Rtranslate-technical-book$CODEX_SKILLS_DIR/cp-Rtranslate-technical-book-parser-first$CODEX_SKILLS_DIR/最小 Python 依赖python3-mvenv .venv .venv/bin/pipinstall-rrequirements.txtPDF 多解析器依赖单独放在requirements-parser.txt中。第一次使用时建议不要直接处理整本书先选 20 页左右的代表性内容并给出明确预算使用 $translate-technical-book-parser-first 把 book.pdf 转成可翻译的 canonical Markdown。 先处理 20 页代表性样本预算不超过 20 次高智能调用通过 QA 后再规划全书。目前的边界它还不是“放进去一本任意 PDF就能自动得到完美中文书”的工具。复杂 PDF 的解析依赖比较重项目还缺少公开的 parser-first 回归夹具和完整的一键 orchestrator。自动检查也只能证明结构和受保护内容没有发现遗漏不能代替人工语义抽检。我们希望先把一件事做好不要在证据不足时装作成功。哪里失败流程就停在哪里哪里需要重试也尽量只重试那一块。项目采用 MIT License不包含实验书籍、译文或原书图片。欢迎试用也欢迎把它扩展到新的学科、语言和解析器。
