文译

阅读外文原版小说时，机器翻译往往破坏了原有的排版、图片和目录结构，导致阅读体验大打折扣。

文译 (trans-novel) 是一个专注于多语言小说汉化的命令行工具。它支持 EPUB、FB2 和 TXT 格式输入，最终输出为保留原书样式、图片、目录和跳转链接的中文 EPUB。

只需一个命令，它即可自动完成预扫、分析、翻译、润色、审校及导出全流程，并支持中断后无缝续跑。

核心亮点：保真、智能、可控

1. 极致保留原书风貌

• EPUB 原生回填：对于 EPUB 输入，译文会按原 XHTML 模板精准回填，完美保留 CSS 样式、插图、超链接和锚点。
• 格式转换：支持将 FB2 或 TXT 转换为结构良好的中文 EPUB；也可通过 --format txt 输出纯文本。

2. 多档位 LLM 协同工作流
默认基于 DeepSeek API，通过配置不同档位的模型平衡质量与成本：

• Strong (强)：负责核心翻译、润色、全局分析及标题翻译，确保文笔流畅准确。
• Cheap (廉)：用于章末 Review、一致性 QA 及回译比对，兼顾效率与校验。
• Fast (快)：处理全书预扫、章节梗概生成、术语抽取等机械性任务，速度优先。

3. 深度一致性保障机制

• 全书预扫：翻译前通读整本书，生成全书概览和逐章梗概，让早期章节也能参考后续剧情走向。
• 动态术语库：自动提取人名、地名、专有名词存入 SQLite 数据库，并在翻译时注入提示词，确保前后统一。
• 滚动上下文：章内分批翻译时，后一批次可见前几段的译文，保持语境连贯。
• 段数对齐与重试：强制模型输出固定段数的 JSON，若不符则自动重试或逐段兜底，防止漏译。

4. 断点续传与状态管理

• 实时保存：每个批次翻译完成后立即写入 state/ 目录。
• 无缝续跑：意外中断后，运行 resume 命令即可从断点继续，已完成的批次自动跳过，节省 Token 和时间。

快速开始

1. 环境准备
确保已安装 uv，并配置 DeepSeek API Key。

# 克隆项目
git clone <repo-url>
cd trans-novel

# 同步依赖
uv sync

# 设置 API Key
export DEEPSEEK_API_KEY=sk-...

2. 执行翻译
最简单的用法，直接指定文件：

uv run trans-novel translate book.epub

翻译完成后，译文 EPUB 将生成在源文件同级目录。运行状态、章节 JSON、术语库和报告保存在 state/ 文件夹中。

3. 常用命令

• 中断后继续：

  uv run trans-novel resume book.epub
  

• 查看进度：

  uv run trans-novel status book.epub
  

• 仅重新导出 EPUB（当修改了样式或想重新打包时）：

  uv run trans-novel tools assemble book.epub
  

• 指定章节翻译（调试用）：

  uv run trans-novel translate book.epub --chapter 3
  

配置与优化

主要配置位于 config.yaml，关键选项包括：

• 语言设置：language.source 默认为 auto（自动识别），也可指定 ja, en, ko 等。
• 流水线控制：
  • pipeline.polish: 是否开启中文润色（默认 true）。润色会增加一次 Strong 模型请求，提升文笔但增加成本。
  • pipeline.review: 是否开启章末审校。
  • pipeline.autofix_severe: 是否自动重译并修复严重错误。
  • pipeline.consistency_qa: 是否开启全书跨章一致性扫描。
• 上下文窗口：
  • segment.max_chars_per_batch: 每批翻译字符数。
  • pipeline.rolling_context_segments: 带入的前文译文段数。

调试技巧：
离线测试时，可将 llm.provider 改为 fake，避免产生实际 API 调用。

辅助工具

文译提供了一系列工具命令，用于后期检查和维护：

• 查看术语库：

  uv run trans-novel tools glossary book.epub list
  

• 检查术语冲突：

  uv run trans-novel tools glossary book.epub conflicts
  

• 运行 QA 检查（汇总问题，不自动修改）：

  uv run trans-novel tools qa book.epub
  

• 生成翻译报告：

  uv run trans-novel tools report book.epub
  

文译通过精细的上下文管理和多模型协作，试图在机器翻译的速度与人工校对的质量之间找到平衡。对于想要快速啃完大部头外文原著的读者来说，它是一个能极大提升幸福感的工具。

如果你手头有一本心仪已久却因语言门槛搁置的外文小说，不妨试试文译，让它帮你打破语言的壁垒。