命令行里的翻译作坊：用文译（wenyi）把一整本外文小说变成高质量中文电子书

本文由 莫潇羽@源码七号站（www.fuyuan7.com）撰写，转载请注明出处。

快速摘要

如果你正在找一款能完整翻译整本外文小说的工具，文译（wenyi）是目前开源社区里最值得关注的选择。它解决的不是"一句话翻译"的问题，而是整本书级别的翻译工程——保留原版EPUB排版、图片、目录和跳转链接，用SQLite术语库确保全书的专有名词翻译一致，支持断点续跑不怕中断，三档大模型分层调度把API翻译成本压到最低。2026年最新的DeepSeek V4系列模型让翻译一本10万字的英文小说成本可以控制在个位数人民币，而翻译质量——有人已经用它翻完了村上春树最新长篇小说《夏帆》，效果相当能打。

一台普通的电脑、一个DeepSeek API Key、几条命令，你就能拥有一间属于自己的"翻译作坊"。这篇文章会从环境搭建、流水线原理、术语管理、质量控制、配置调优到实操体验，把文译拆解干净。想看完整拆解，往下翻。

一个被忽略的刚需：当你想读一本没有中文版的小说

不知道你有没有过这种经历。

某天刷到一本外文小说推荐，简介写得勾人心弦，评论区一片好评。你兴冲冲搜了一圈，发现——没有中文版。出版社没有引进计划，民间汉化组也还没开工。唯一的办法就是硬啃原文，但对自己的外语水平实在没有信心。

打开某个通用翻译工具，复制粘贴了几段文字进去，翻译结果倒也凑合。可当你试图把整本书导入进去的时候，问题就全来了：段落被打散成了一地碎片，图片消失了，目录失效了，章节之间的跳转链接全部变成死链接。更要命的是，第一章主角叫"艾伦"，翻到第五章变成了"阿兰"，再往后又成了"艾倫"——同一个人名在不同章节出现了三四种译法，阅读体验直接崩盘。

这还只是短篇小说。如果是一本几十万字的长篇，你用通用翻译工具翻到一半电脑蓝屏或者网络断了，之前跑了好几个小时的进度全部归零——那种绝望感，经历过的人都懂。

长篇小说的翻译跟普通文本翻译完全是两码事。它不是把一段段文字丢进翻译引擎就完事了，而是一个需要上下文一致性、术语统一、格式保持、断点容错的系统工程。市面上大多数翻译工具在设计时根本没有考虑过"整本书"这个场景，它们擅长的是短文本、对话、邮件——碰到长篇小说就原形毕露。

直到文译（wenyi）出现。

这个由开发者 BigDawnGhost 基于个人兴趣打造的开源项目，把"整本小说的翻译"这件事做成了一个高度自动化的命令行流水线。翻译前预扫全书建立梗概和术语库，翻译中滚动上下文保持连贯，翻译后逐章审校、标点规范化、跨章一致性检查——整套流程走下来，翻译出来的中文电子书读起来真的像那么回事。

我是在2026年初接触到这个项目的，折腾了大半年，用它翻完了好几本日文和英文小说。下面这篇长文，就是我把整个工具的原理、配置、实操、踩坑经验揉在一起写成的。没有废话，直接上干货。

文译（wenyi）到底是什么

先给文译下一个清晰的定义。

文译是一个基于大语言模型的命令行翻译工具，专门用来把多语言EPUB、FB2或TXT格式的小说翻译成中文。它托管在GitHub上（github.com/BigDawnGhost/wenyi），采用MIT协议开源，这意味着你可以自由使用、修改甚至基于它二次开发。项目目前积累的Star数相当可观，在阮一峰的科技周刊和HelloGitHub上都获得过推荐。

和传统翻译工具相比，文译有几个根本性的不同。

第一，它把"整本书"当作一个完整的翻译单元来对待。不是逐句丢给翻译引擎，而是在翻译前先通读全书，建立故事梗概和术语表。这样一来，翻译第一个章节的时候，模型就已经知道后面的情节走向和人物关系，避免了"翻到后面才发现前面的某个词翻译错了"的情况。这一点非常关键——人在翻译一本书的时候，也是先通读再动笔的。

第二，它有一套完整的翻译工厂流水线。不是"输入→翻译→输出"这么简单，而是"预扫→全局分析→术语抽取→分章翻译→润色→章末审校→标点规范化→组装导出"，每一步都可以独立开关和配置。

第三，它采用了三档模型分层调度的设计。核心翻译用顶级模型保证质量，审校和一致性检查用中档模型控制成本，全书预扫和术语抽取用最快的模型提高效率。这种"好钢用在刀刃上"的思路，让翻译一本长篇小说的综合API成本变得极为可控。

2026年7月，村上春树睽违三年的最新长篇小说《夏帆》日文版首发，短短几天之后就有技术爱好者用AI翻译工具做出了精译中文版本。虽然不能确定用的是不是文译，但这个事件本身就是一个标志：AI翻译长篇文学作品已经从"能不能用"进入到了"好不好用"的阶段。而文译，就是这个阶段里最值得深入研究的开源方案之一。

下面这张表可以帮你快速了解文译的核心能力：

看完这张表，你应该对文译能做什么、好在哪有了一个整体印象。接下来，我从最基础的环境搭建开始，一步一步把整套流程说清楚。

环境准备与快速上手：三条命令跑起来

文译的运行环境不算复杂，但如果你的电脑上缺少必要的依赖，可能会在安装步骤卡住。我下面把完整的准备流程捋一遍，跟着走就行。

你需要准备什么

硬件方面几乎没什么要求。文译本身不跑本地模型，翻译任务都通过API调用远程的大语言模型来完成，所以对CPU和GPU都没有特殊需求。一台能正常联网的电脑、稳定的网络连接，就够了。

软件方面需要三样东西：

• Python 环境：文译使用 uv 作为包管理器，uv 会帮你在项目目录下创建隔离的虚拟环境。所以不需要手动安装Python特定版本，但系统中最好有一个可用的Python。macOS和大多数Linux发行版都自带Python，Windows用户可以去python.org下载安装。
• Git：用来克隆GitHub仓库。macOS和Linux一般系统自带，Windows用户需要去 git-scm.com 下载。
• 一个DeepSeek API Key：这是翻译引擎的核心。2026年DeepSeek V4系列的价格非常低廉，后面会有详细的成本分析。境外模型使用需遵守国内网络与内容管理相关规定，DeepSeek是国内公司深度求索的产品，API接入完全合规，可以直接用支付宝或微信充值。

安装三步走

第一步，克隆仓库：

git clone https://github.com/BigDawnGhost/wenyi.git
cd wenyi

第二步，安装依赖。文译使用 uv 管理Python依赖，一条命令搞定：

uv sync

uv sync 会自动创建虚拟环境并安装 pyproject.toml 里声明的全部依赖包。如果你还没有安装 uv，可以参考 Astral 官方文档先装好，macOS 和 Linux 一条 curl 命令、Windows 一条 PowerShell 命令就能装好。

第三步，配置API Key。文译默认使用DeepSeek的API，你需要把Key写入环境变量：

export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

如果你希望持久化存储，把Key写进 .env 文件：

echo "DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx" > .env

DeepSeek的API Key可以在 platform.deepseek.com 注册账号后在"API Keys"页面创建。API价格变动较快，截至2026年7月写稿时，DeepSeek V4-Pro 已引入分时定价机制：平峰时段（夜间、周末全天）百万tokens输入（缓存命中）0.025 元、输出 6 元；高峰时段（工作日 9:00 到 12:00、14:00 到 18:00）价格翻倍，输出涨至 12 元。这个价格水平意味着什么我们后面会细算，不过有一点可以先说——文译这种离线批处理翻译任务完全可以安排在夜间或周末跑，全程享受平峰价。

跑通你的第一次翻译

三条命令走完，就可以开始翻译了。假设你有一本叫 novel.epub 的英文小说：

uv run trans-novel translate novel.epub

敲下回车之后，文译会开始执行一整套翻译流水线——从预扫全书到最终导出中文EPUB。屏幕上会实时输出当前进度，你看到的大致是这样：

[预扫] 正在分析全书结构...
[预扫] 检测到 24 个章节，总字数约 12 万字
[术语] 已抽取 47 个专有名词
[翻译] 第1章 / 24...
[翻译] 第1章完成，用时 3m 12s
[翻译] 第2章 / 24...
...

翻译完成后，源文件目录下会多出一个中文EPUB文件，直接丢进任何阅读器就能读。所有中间状态保存在 state/ 目录下，包括每章的译文JSON、术语库、翻译报告等等。

如果翻译中途因为网络波动或其他原因中断了，不需要从头开始，跑这条命令续上：

uv run trans-novel resume novel.epub

文译会自动跳过已经翻译完成的章节，只补翻未完成的部分。API额度不会浪费在重复翻译上。

第一次跑通之后，你可能会对 config.yaml 里的各种参数产生好奇——哪些开关该打开、哪些可以关掉省成本？别急，我们先从文译最巧妙的设计开始讲起：三档模型分层调度。

三档模型分层调度：翻译成本控制的精妙设计

如果说文译有一个让我觉得"这设计真聪明"的地方，那一定是它的三档模型分层调度机制。

用过AI翻译工具的朋友都有这种体会：如果你全程用最强的模型翻译，质量确实好，但成本也高得肉疼，一本长篇小说翻下来几百块就出去了。如果你全程用便宜模型，成本下来了，但译文质量一言难尽，各种错译漏译，读起来比机翻还难受。

文译的解法是把翻译任务拆成不同"重量级"的子任务，然后分别分配给不同档位的模型。它定义了三个层级：

• strong（强力档）：承担核心翻译任务——正文翻译、全局内容分析、标题翻译、以及可选的润色环节。这些是对译文质量影响最大的步骤，不能省。
• cheap（经济档）：承担质量检查任务——章末审校、跨章一致性QA、回译比对。这些任务不需要创造力，只需要判断"有没有问题"，性价比模型完全够用。
• fast（快速档）：承担机械性任务——全书预扫、章节梗概生成、术语抽取。这些任务对模型能力要求最低，用最快的模型跑完就好。

分层调用的设计思路用一个类比来说就是：你请了一位资深翻译（strong）来做正文翻译，请了一位校对编辑（cheap）来做审核，又请了一位实习生（fast）来做前期的资料整理和术语摘录。专业的人做专业的事，整体效率最高、成本最低。

2026年的成本到底有多低

我来算一笔实际的账。以DeepSeek V4系列为例，2026年的定价如下（价格变动快，下表为写稿时的近似行情，请以官方定价页面实时数据为准）：

现在假设我们要翻译一本10万英文单词的小说。一般情况下，10万英文单词大约对应15万个token。翻译成中文后，输出大约12到14万个token。加上Prompt消耗的上下文token，每章大约需要消耗输入3000到5000个token、输出2000到4000个token。

一本24章的小说：

• strong档消耗：翻译24章，每章平均输入4000 token、输出3000 token。输入总计96000 token，输出总计72000 token。输入费用：96000 × (1/1000000) × 3 ≈ ¥0.29（按未命中估算），输出费用：72000 × (1/1000000) × 6 ≈ ¥0.43。翻译正文本身合计不到一块钱。
• cheap档消耗：审校24章，每章平均输入3000 token、输出500 token。总计约 ¥0.10。
• fast档消耗：全书预扫一遍，输出梗概和术语，大约消耗输入20000 token、输出5000 token。总计约 ¥0.04。

整本书翻下来，API费用大概在几毛到两三块钱之间。 这个数字放在两年前是想都不敢想的。即便你的小说篇幅翻倍到20万字，或者换用其他对中文支持稍弱的模型、导致token消耗增加，总费用也很难超过10块钱。

当然，以上是理想情况下的估算。实际翻译中，如果开启了润色（polish）、回译抽检（backtranslate_sample）、跨章一致性QA（consistency_qa）等附加功能，消耗会相应的增加。但即便如此，文译的三档分层设计已经帮你把成本踩到了最低——review和QA用的是cheap档，不回吐正文翻译用的strong档。

另外需要特别注意：以上成本估算是按平峰时段价格算的。DeepSeek V4-Pro 自2026年7月起采用分时定价，高峰时段（工作日 9:00 到 12:00、14:00 到 18:00）价格翻倍——输入涨至 6 元/百万tokens，输出涨至 12 元/百万tokens。如果你在高峰时段跑翻译，整本书的费用可能会翻倍。好在文译是离线批处理任务，完全可以在晚上或周末跑，全程平峰价，成本依然控制在几块钱以内。价格变动快，请以官方定价页面的实时数据为准。

模型配置怎么写

在 config.yaml 中，三档模型的配置长这样：

llm:
  tiers:
    strong:
      provider: "deepseek"
      model: "deepseek-v4-pro"
      api_key_env: "DEEPSEEK_API_KEY"
    cheap:
      provider: "deepseek"
      model: "deepseek-v4-flash"
      api_key_env: "DEEPSEEK_API_KEY"
    fast:
      provider: "deepseek"
      model: "deepseek-v4-flash"
      api_key_env: "DEEPSEEK_API_KEY"

如果你想换模型——比如用其他兼容OpenAI SDK的API——只需要改 provider、model 和对应的环境变量即可。理论上任何兼容OpenAI接口的服务都可以接入，只要模型能力足够。

还有一个非常实用的调试功能：fake模拟模式。把模型设为 fake，文译会跳过实际的API调用，用模拟数据跑完整条流水线。这个模式不消耗任何API额度，适合在正式翻译前调试配置、测试分段策略和流水线参数。对于第一次上手的用户来说，先用fake模式跑一遍确认没问题，再切回真实模型，是个稳妥的做法。

llm:
  tiers:
    strong:
      provider: "fake"
      model: "fake"

好，模型配置搞清楚了，下一步我们深入文译最核心的东西——那条从预扫到导出的完整翻译流水线到底是怎么运转的。

翻译流水线深度拆解：从预扫到导出每一步都在做什么

把一本外文小说丢给文译，敲一条命令，等一段时间，得到一本排版完整的中文电子书——整个过程看起来就像变魔术。但这个魔术的背后，是一条设计精密的翻译流水线。

我用Mermaid画了一张流水线的全景图，先看一眼全局再逐步拆解：

flowchart TD
    A[ 输入 EPUB/FB2/TXT] --> B[ 全书预扫]
    B --> C[ 生成全书概览 + 章节梗概]
    C --> D[ 术语自动抽取]
    D --> E[ 分章翻译 loop]
    E --> F{是否开启润色?}
    F -->|是| G[ 中文润色]
    F -->|否| H[ 章末审校]
    G --> H
    H --> I{严重问题自动修复?}
    I -->|是| J[ 自动重译问题段落]
    I -->|否| K[ 标点规范化]
    J --> K
    K --> L{更多章节?}
    L -->|是| E
    L -->|否| M[ 跨章一致性 QA]
    M --> N[ 组装 EPUB 导出]
    N --> O[ 输出中文电子书]

下面我把每一个关键环节拆开来讲。

环节一：全书预扫（Pre-scan）

在正式翻译开始之前，文译会先用fast档模型通读一遍整本书。这一步的目的不是为了翻译，而是为了理解——理解这本书讲的是什么故事、有哪些主要人物、世界观设定是什么样的、叙事风格是哪种类型。

预扫之后，fast模型会输出两份产物：一份全书概览，概括整本书的情节脉络和核心设定；一份逐章梗概，把每一章的主要内容用一两段话提炼出来。

这两份产物有什么实际的用途？它们会被注入到后续每一个章节的翻译提示词中。也就是说，模型在翻译第1章的时候，就已经通过全书概览知道了第20章会发生什么；在翻译某个配角出场的场景时，已经通过梗概了解了这个角色的身份和命运走向。这种"全局视角"对长篇小说翻译至关重要——很多伏笔和隐喻如果只看当前章节是无法正确理解和翻译的。

环节二：术语自动抽取

预扫完成后，fast模型会从全书中抽取专有名词——人名、地名、机构名、虚构世界观中的特殊概念——然后存入本地的SQLite术语库。这一步的具体机制我放在下一章专门讲。

环节三：分章翻译（核心环节）

这是整条流水线中消耗时间最长、消耗API额度最多的环节。文译按照原书的章节结构，一章一章地送进strong模型翻译。

但"送进去翻译"这件事远比想象中复杂。文译在这里有两个关键设计：

滚动上下文（Rolling Context）。一章之内可能有好几十个段落，如果一次性全部送给模型，可能会超出上下文窗口或者让翻译质量下降。文译的做法是把一章拆成多个批次，每个批次翻译N段。关键在于：下一个批次在翻译时，会把上一个批次已经翻译好的前几段中文译文附在Prompt里，作为上下文参考。这样一来，模型能看到"前面翻成了什么样"，翻译风格和用词习惯就能在批与批之间自然延续。

段数对齐（Segment Alignment）。模型有时候会"偷懒"——你送进去10段原文，它只返回8段译文，或者把两段合并成一段。文译做了强制约束：输入N段，输出必须是N段JSON数组。如果段数对不上，自动重试。这个机制保证了翻译后的电子书段落结构和原文完全一致，不会出现莫名其妙的段落合并或拆分。

每章翻译完成后，译文以JSON格式保存在 state/ 目录下，每个段落对应一条记录。这种结构化存储的好处是后续的审校、QA、重新导出都可以精确定位到任意段落。

环节四：中文润色（可选）

正文翻译完成后，如果你在 config.yaml 中开启了 pipeline.polish，strong模型会再对本章译文做一次润色。润色的目标是让中文更自然流畅——消除翻译腔、调整语序、替换生硬的直译表达。

润色环节是可选的，因为它会额外消耗API额度。根据我的实测经验，对于本身语言风格比较平实的小说（比如大多数轻小说和通俗文学），润色带来的提升不算明显，可以关掉省成本。但对于文学性较强、修辞手法丰富的作品，润色能让译文的中文阅读体验提升一个档次。

环节五：章末审校（Review）

这是质量控制的第一个关口。cheap模型会逐段检查译文是否有以下问题：

• 漏译：原文有一段，译文里对应的位置是空的或者明显少翻了内容。
• 误译：译文的意思和原文偏差太大，可能是模型理解错了某个多义词或者复杂句式。
• 术语冲突：某个专有名词的翻译和术语库里记录的不一致。
• 人称混乱：男女他、单复数等在翻译中搞混了。

审校结果会标记出"严重"和"轻微"两个级别的问题。如果开启了 pipeline.autofix_severe，严重问题会被自动送回strong模型重译。

环节六：标点规范化

这个环节虽然不起眼，但非常影响阅读体验。模型翻译出来的中文有时会混用半角标点（英文标点）和全角标点（中文标点），引号有时是 "" 有时是 「」。文译会在每章末尾统一将标点规范化为中国大陆常用的全角中文标点——句号。、逗号，、双引号""、书名号《》等。

环节七：跨章一致性QA（可选）

所有章节翻译完成后，如果你的书超过一定章数且开启了 pipeline.consistency_qa，cheap模型会对全书做一次跨章节的一致性扫描。它会检查：

• 同一个角色在不同章节的译名是否一致
• 前后章节对同一个地点、事件的描述是否存在矛盾
• 术语库中登记的词条是否在全书范围内统一使用

全流程跑完之后，最后一步是根据原书的XHTML模板（EPUB的情况）或自动生成的EPUB结构（TXT的情况），把译文回填进去，打包导出。一本排版完整、图片齐全、目录可点击、跳转链接生效的中文EPUB电子书就诞生了。

术语管理：让「张三」不会变成「张四」的秘密武器

如果你只用过通用翻译工具翻小说，那你一定被术语不一致的问题折磨过。同一个角色名字在第一章叫"伊丽莎白"，翻到第三章变成了"伊莉莎白"，到了第七章又成了"以利沙伯"——读者不疯才怪。

小说翻译中术语一致性的重要性怎么强调都不过分。尤其是奇幻和科幻类作品，充斥着大量作者自创的专有名词——人名、地名、魔法体系、科技概念、组织名称——如果这些词的翻译不统一，整个阅读体验就是灾难。

文译的解决方案是一套基于SQLite的术语库系统，它贯穿翻译流水线的多个环节，确保专有名词全书统一。

术语库是怎么工作的

整个术语管理流程可以拆成四步：

第一步：自动抽取。 在全书预扫阶段，fast模型会从原文中识别出专有名词——人名（John Smith）、地名（Hogwarts）、机构名（The Ministry of Magic）、自创词（Muggle）——然后自动插入到SQLite术语库中，同时给出一个初步的中文翻译建议。

第二步：人工确认（可选但推荐）。 自动抽取的结果不一定完美。模型可能会漏掉一些不那么明显的术语，也可能把一些普通词汇误判为术语。文译提供了一个 glossary list 命令，可以把术语库里的全部词条列出来供人检查。你可以在正式翻译前打开术语库，手动补充遗漏的词条、修正不准确的翻译建议。

# 列出所有术语
uv run trans-novel tools glossary book.epub list

# 检查术语冲突
uv run trans-novel tools glossary book.epub conflicts

第三步：提示词注入。 在每个批次的翻译请求中，文译会把术语库中与当前章节相关的词条注入到Prompt里。比如当前章节出现了"Hermione"这个词，Prompt中就会包含一条"请将 Hermione 翻译为「赫敏」"的指令。模型在翻译时会优先遵循这些术语指令。

第四步：持续更新。 翻译过程中如果模型遇到了术语库中没有的新术语，会自动补录进去。这意味着术语库是动态增长的，越翻越完整。

术语库的数据结构

术语库底层是一张SQLite表，结构大致如下：

CREATE TABLE glossary (
    id INTEGER PRIMARY KEY,
    source_term TEXT NOT NULL,      -- 原文术语
    target_term TEXT NOT NULL,       -- 中文翻译
    category TEXT,                   -- 分类：人名/地名/组织/概念
    context TEXT,                    -- 首次出现的上下文
    confirmed INTEGER DEFAULT 0,     -- 是否人工确认
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

每个术语都有"confirmed"状态标记。自动抽取的词条默认为未确认，人工审核过的标记为已确认。在提示词注入时，已确认的词条会被强制要求遵循，未确认的词条作为参考建议。

一个真实例子

举个实际例子帮助理解术语库的作用。假设你在翻译《哈利·波特》英文原版，术语库里可能会自动抽取出这些条目：

有了这张表，无论书中哪个章节出现这些词，翻译结果都保持一致。不会出现第一章叫"邓布利多"、第十章叫"丹伯多"的情况。

术语库还有一个非常实用的场景：如果你连续翻译同一个作者的系列小说，可以把第一本书积累的术语库复用到后续作品中。同一个虚构世界里的地名、魔法体系、角色名字都能延续之前的翻译，省去了大量重复劳动。

质量控制体系：五道防线保证译文可读性

翻译质量不是靠"模型强"就能保证的。再强的大模型也会犯错——有时候是漏翻，有时候是上下文理解偏差，有时候是术语搞混。文译在翻译流水线中嵌入了五道质量控制防线，每一道解决一类特定的问题。

下面这张表先给你一个整体视图：

防线一：全书理解

这个前面已经详细讲过了。核心价值在于——翻译第一章的时候模型就已经知道最后一章的结局，翻译质量从第一段开始就有全局视角的支撑。在传统的"逐章翻译"模式下，前几章的翻译质量往往最差，因为模型缺乏对全书的了解。文译用预扫机制解决了这个问题。

防线二：滚动上下文

这是一个很巧妙的设计。大语言模型在翻译时有一个特点：如果没有任何上下文参考，它倾向于给出"最安全"的翻译，也就是最常见、最直白的译法。但如果它看到了前几个段落的译文风格——比如人称用"他"还是"她"、对话的语气偏正式还是偏口语、某个人名已经被翻译成了什么——它就会自然地延续这种风格。

滚动上下文的实现细节：每个批次默认翻译8到12个段落，下一个批次的Prompt会附带上一个批次最后3段的译文。这3段"交叠区"就像接力棒，把风格和用词习惯传递下去。

防线三：段数对齐

这个问题比很多人想象的要常见。当你要求模型"翻译以下10段文字，返回10段译文"时，模型有时候会自作主张地把第3段和第4段合并成一段（原文是对话+描写，模型觉得合在一起更"通顺"），或者把一段拆成两段。对于普通聊天场景这不是什么问题，但对于电子书格式来说，段落数不对意味着排版全乱。

文译的做法很直接：严格要求模型输出N段JSON，如果返回的不是N段，就直接重试。重试时会附带更明确的格式要求。根据文译开发者提供的测试数据，在DeepSeek V4系列模型上，首次翻译的段数对齐成功率在95%以上，加上一次重试后基本能达到99%以上。

防线四：章末review

这是质量控制的主力环节。每章翻译完成后，cheap模型会拿到"原文+译文"的对照版，逐段审查以下维度：

• 完整性：原文的每一段在译文中都有对应的段落，没有遗漏。
• 准确性：译文没有明显的理解错误。常见的错误类型包括：多义词选错义项（比如"bank"在上下文中明明是"河岸"却被翻成了"银行"）、复杂长句的语法结构解析错误、文化专有项的翻译不当。
• 术语一致性：译文中的专有名词和术语库记录的一致。
• 人称代词：中文里"他""她""它"发音相同但在书面必须区分，模型有时会搞混。

review结果以JSON格式返回，每段标记"pass""warning""severe"三个等级。warning级别的段落记录问题但不阻塞流水线，severe级别的如果开启了 autofix_severe 就自动送去重译。

防线五：跨章一致性QA

全书翻译完成后，cheap模型会做一次跨章扫描。这一步主要解决的是"前文和后文对不上"的问题——比如第3章提到某个角色"三十岁出头"，到了第15章变成了"年近四十"；第5章说某个地点"位于城东"，第12章变成了"城西"。

跨章QA的结果不会自动修改译文（因为可能涉及到情节理解，自动修改风险太高），而是生成一份报告供人工判断。这份报告会列出所有可疑的不一致之处，附上原文和译文的上下文。

五道防线构成了一个从"事前预防"到"事中控制"到"事后检查"的完整质量闭环。我的使用体会是：大部分小说经过这五道防线后，译文已经可以直接阅读。需要人工介入的情况主要集中在文学性特别强的段落——比如诗歌、双关语、文化隐喻——这些确实超出了当前AI模型的能力边界，即使人工翻译也是难点。

断点续跑与状态管理：翻译一百万字也不怕

长篇小说翻译最怕什么？不是翻译质量不够好——质量差可以打磨——而是翻译到一半，跑了好几个小时甚至几十个小时，突然因为网络波动、电脑休眠、程序崩溃或者停电，进度全丢，API额度白烧。

文译的断点续跑机制，是我认为它在工程实现上最成熟的部分之一。

state目录里存了什么

翻译一本小说时，文译会在项目目录下创建一个 state/ 文件夹，里面按照源文件名组织子目录。以 novel.epub 为例，目录结构大概长这样：

state/
└── novel.epub/
    ├── book_overview.json      # 全书概览
    ├── chapter_summaries.json  # 逐章梗概
    ├── glossary.db             # SQLite术语库
    ├── chapters/
    │   ├── ch_001.json         # 第1章译文（含原文+译文对照）
    │   ├── ch_002.json         # 第2章译文
    │   └── ...
    ├── reviews/
    │   ├── ch_001_review.json  # 第1章审校结果
    │   └── ...
    ├── progress.json           # 翻译进度追踪
    └── reports/
        └── qa_report.json      # 跨章QA报告

每个 ch_XXX.json 文件里存储了该章的完整翻译数据：每个段落的原文文本、译后文本、段落序号、翻译状态（pending/translated/reviewed/polished）。这种细粒度的状态记录，使得"中断后从哪儿继续"变得非常简单——程序只要检查每个段落的状态字段，跳过已完成的，只处理未完成的。

四个核心指令的使用场景

文译围绕状态管理提供了四个指令，覆盖了日常使用的全部场景：

translate — 启动翻译。如果是第一次翻译这本书，会从预扫开始走完整流水线。如果 state/ 目录下已经有之前的翻译记录，会自动检测并跳过已完成的部分。

resume — 续翻。当翻译被中断（按了Ctrl+C、网络断了、电脑重启等等），用这个命令无缝接上。它和 translate 的内部逻辑基本一致，但更明确地表达"我是从中断恢复"的意图。实际上，直接再跑一次 translate 也能达到同样效果，因为文译每次都检查状态。

status — 查看进度。把当前翻译进度用表格打印出来：

uv run trans-novel status novel.epub

输出会显示每一章的状态：预扫完成、翻译完成、审校完成、润色完成、待处理。一目了然。

tools assemble — 单独导出EPUB。如果你只是想重新生成一遍EPUB文件（比如改了样式配置或者想导出纯文本），不需要重新翻译，直接用这个命令从已有的 state/ 数据重新组装：

uv run trans-novel tools assemble novel.epub

这个命令还有一个重要用途：如果翻译全跑完了但最终导出的EPUB有什么问题（比如元数据没写对、封面图没放进去），你可以修好配置后重新assemble，而不用重新翻译全书。

实战场景：分批翻译一本百万字巨著

假设你在翻一本字数特别多的小说——比如俄罗斯文学那种动辄四五十万字的巨著——一口气翻完不现实。我的做法是：

1. 先跑一次 translate，让它翻完前几章。
2. 按 Ctrl+C 中断。
3. 过几天有时间了，跑 resume 继续翻几章。
4. 重复，直到翻完全书。
5. 最后跑 tools assemble 导出成品。

整个过程中，已经翻译的章节纹丝不动地躺在 state/ 目录里，一分钱API额度都不会浪费。

格式处理：EPUB/TXT/FB2的原生支持是怎么做到的

如果你用过传统翻译工具处理EPUB文件，你一定经历过这样的噩梦：把EPUB文件导入工具 → 工具解压出一堆HTML和CSS → 提取纯文本 → 翻译纯文本 → 输出一个排版全毁的文档。封面图丢了，插图不见了，目录链接全变死链，CSS样式荡然无存。

文译对这个问题的解法是：不解构，只替换。

EPUB的本质

先花两句话科普一下EPUB格式。EPUB本质上是一个ZIP压缩包，里面包