为什么自己做一个 EPUB 翻译器比你想象的难得多

最近，一位叫 @cat88tw 的开发者在推特上分享了用 Claude Code 构建 EPUB 翻译器的经历，引起了广泛共鸣。这条推文获得了 1,671 次浏览——不是因为这个想法多新奇，而是因为每一个试过同样事情的开发者都深有同感。

思路看起来很简单：EPUB 不过是把 HTML 和 CSS 打包成 ZIP，现在的 AI 模型翻译能力又很强，把两者连起来不就行了？一个周末应该能搞定。

但现实是，一个周末只够你做出一个能跑但处处是坑的原型。想要真正处理现实世界中各种各样的书籍，保留排版、不丢内容、不乱码——这是一个货真价实的工程难题。

难点一：EPUB 结构远比你以为的复杂

EPUB 文件本质是一个 ZIP 压缩包，里面包含 XHTML 文件、CSS 样式表、图片、字体、元数据和导航系统。EPUB 2 和 EPUB 3 两个标准定义了这些文件的组织方式，但出版商对标准的理解和执行千差万别。

有的书每章一个文件，有的把所有内容塞进一个巨大的 XHTML 文件里。有的用 <div> 嵌套表示章节，有的用 <section>，有的完全没有语义化标签。目录可能是 NCX 文件、Navigation Document，或者两者都有。CSS 有的内联，有的外部引用。字体有的嵌入，有的依赖系统。

你的翻译器需要正确处理所有这些变体。一旦你做了任何假设——比如"每章一定是独立文件"或"CSS 一定是外部引用"——你马上就会遇到一本打破这个假设的真实书籍。

OPF 清单文件列出了书中的每一个资源和阅读顺序。如果你的翻译器增删或重命名了文件却没有更新清单，生成的 EPUB 就是无效的，大部分阅读器会拒绝打开或显示异常。

难点二：替换文字的同时保留格式

这是大多数自建项目失败的地方。翻译文字是容易的部分，翻译完之后保持格式不变才是真正的噩梦。

考虑一个包含混合格式的段落：

<p>
  作者指出，<em>这一特定发现</em>具有<strong>统计显著性</strong> （p <
  0.001），详见<a href="chapter3.xhtml#table2">表 2</a>。
</p>

你的翻译器需要在保留 HTML 标签的前提下提取可翻译文本，把翻译后的文本映射回正确的标签——即使目标语言的词序、句子结构和文本长度完全不同——同时保留不应被翻译的超链接引用，还要正确处理 HTML 实体。

如果你直接把原始 HTML 发给语言模型让它翻译，模型经常会弄乱标签、修改属性值、漏掉闭合标签或重写整个标记结构。如果你先去掉 HTML 再翻译纯文本，所有格式就丢了，也没办法还原。

现在把这个问题乘以书中出现的每一种格式：脚注、上标、注音标注、首字下沉、引用块、诗歌换行、数学公式、合并单元格的表格……每一种都是你的映射逻辑需要单独处理的特殊情况。

难点三：分段处理与上下文窗口

一本典型的书有 6 万到 10 万字。目前没有任何语言模型能在一次 API 调用中处理整本书并返回连贯的翻译。你必须把书分成多个块来处理。

但分段本身就引入了新问题：

• 上下文丢失：一个块末尾的句子可能引用了下一个块开头的内容。人名、术语和代词需要跨块保持一致的翻译。
• 分割点选择：如果在段落、列表或表格中间分割，会产生破碎的 HTML。即使在段落之间分割，也可能丢失上下文。
• 术语一致性：同一个词在不同的块中可能被翻译成不同的结果。一个日文小说中叫"月"的角色，可能在一章被翻译成"月"，在另一章变成"Moon"。

专业的翻译工具会维护术语表和跨块重叠的上下文窗口。正确地构建这些机制需要精心的工程设计，而不是简单地按段落边界切割然后各自处理。

难点四：CSS 和字体处理

翻译文本会改变文本长度。一个 20 词的英文句子可能变成 35 个德语词或 12 个中文字符。这会产生连锁反应：

• 固定宽度容器会溢出或留下尴尬的空白
• CSS 多列布局在内容长度剧变时会断裂
• 竖排文本布局（日文书中常见）需要与横排完全不同的 CSS 规则
• 自定义字体可能不包含目标语言的字形。一本使用纯拉丁字体排版的书，翻译成中文或阿拉伯文后会显示空白方块或回退字体
• 行高和间距针对一种文字优化后对另一种文字就不合适。中日韩文字需要更大的行高，阿拉伯文字需要不同的基线对齐

你的翻译器要么需要为目标语言调整 CSS 属性，要么接受输出效果会有问题。两个选项都不简单。

难点五：中日韩文字和 RTL 排版

如果你的翻译器只处理欧洲语言，还可以忽略文字系统特有的问题。一旦加入中文、日文、韩文或阿拉伯文的支持，复杂度翻倍。

中日韩文字的挑战：

• 分词——中文和日文不使用空格分词，你的分块逻辑不能依赖空白字符
• 注音标注（振假名）——汉字上方的读音提示需要保留或为翻译后的文本重新生成
• 标点规则不同——中文使用全角标点，日文有特定的换行规则
• 竖排书写在许多日文和繁体中文书籍中是标准格式

RTL（从右到左）文字的挑战：

• 阿拉伯文和希伯来文从右到左排列，这不仅影响文字方向，还影响整个页面布局
• 双向文本（同一段落中混合英文和阿拉伯文）需要正确的 Unicode BiDi 算法处理
• 阿拉伯文是连笔书写——字母的形状根据在单词中的位置而变化。如果你的 HTML 处理在标签边界错误地拆分了一个单词，渲染就会出错

大多数开发者直到用户尝试把一本书翻译成中文或阿拉伯文并反馈输出无法阅读时，才发现这些问题。

难点六：EPUB 验证和阅读器兼容性

生成一个在所有阅读器上都能正确显示的有效 EPUB，出乎意料地困难。电子书阅读器不是浏览器——它们各自实现了 EPUB 标准的不同子集，并带有自己的怪癖。

• Apple Books 支持 Kindle 忽略的 EPUB 3 特性
• Kobo 的 CSS 处理方式和 Google Play Books 不同
• 旧版 Kindle 设备需要转换成 MOBI 格式，且有严格的格式限制
• 有的阅读器遇到格式错误的 XHTML 会崩溃，有的会静默修复

翻译后的输出需要通过 EPUB 验证（epubcheck），并在主要平台上正确渲染。跨阅读器测试耗时且会暴露各种平台特有的 bug。

难点七：大规模的错误处理

一本书不是一次 API 调用。翻译一本 300 页的书可能需要 200 多次 API 调用。每一次调用都可能失败——频率限制、超时、格式错误的响应、内容过滤或翻译质量问题。

你的翻译器需要：

• 带指数退避的重试逻辑
• 进度追踪，以便从中断处恢复
• 输出验证，在打包最终 EPUB 之前捕获损坏的 HTML
• 成本预估，让用户在开始前就知道费用

为数百个顺序 API 调用构建可靠的基础设施——包括错误处理和断点续传——本身就是一项重要的工程工作。

为什么应该用专门的工具

以上每个难点都是可以解决的。但同时解决所有这些问题——并且随着 EPUB 标准演进、语言模型 API 变更和新的边界情况出现而持续维护——这是一份全职工作。

这正是 EPUBTranslator 存在的意义。你不需要花几周时间搭建和调试自己的流水线，只需要上传文件、选择语言，就能拿到格式正确的翻译 EPUB。这个工具处理了上面描述的所有复杂性：结构解析、格式保留、分块管理、CSS 调整、中日韩和 RTL 支持、验证以及错误恢复。

如果你是享受挑战的开发者，自建 EPUB 翻译器是一个很好的学习项目。你会深入了解 EPUB 格式、HTML/CSS 的各种边界情况以及语言模型 API 的实际限制。但如果你的目标只是读一本外语好书——而不是花一个月调试 XHTML 解析的边界情况——专门的工具能帮你省下大量时间。

那位推文火了的开发者已经用亲身经历验证了这一点。你不必重蹈覆辙。