ePubTsuyaku 

在 AI 翻译日益普及的今天，处理长篇 EPUB 电子书（如轻小说、网文）仍面临三大挑战：上下文连贯性差、格式结构丢失、长任务中断后无法续跑。

ePubTsuyaku 不是一个简单的“整章机翻”脚本，而是一条精心设计的完整翻译流水线。它通过串行摘要、并行翻译、自动校对和断点续跑机制，在保留原书 XHTML 结构、目录和资源的前提下，实现高质量、高效率的 EPUB 翻译。

核心亮点：为何选择 ePubTsuyaku？

1. 上下文感知，拒绝“漂移”

• 按 Spine 顺序处理：严格遵循 EPUB 的阅读顺序，避免章节错乱。
• 串行摘要 + 并行翻译：先生成全书章节摘要以建立全局上下文，然后在翻译时将当前章节上下文“冻结”，确保角色关系和设定不随批次处理而漂移。

2. 断点续跑与自动重试

• progress.json 机制：记录每一步进度，任务意外中断后可自动从断点继续，无需从头再来。
• 低分自动重翻：每个翻译批次都会经过结构化校对，若评分低于阈值（默认 85 分），系统会自动反馈并重翻，确保译文质量。

3. 风格继承：前作参考模式

• Reference EPub 支持：提供已翻译的前作作为参考，提取系列惯用译名、表达习惯和文风提示，确保多部作品间术语和语气的一致性。

4. 高保真结构保留

• 非纯文本重建：尽量保留原始 EPUB 的 XHTML 结构、CSS样式、图片和元数据，而非简单转换为纯文本再重新排版，极大减少后期人工调整工作量。

5. 双模交互：CLI & Web UI

• Web UI：内置文件上传、参数调整、实时进度日志查看和结果下载，操作直观。
• CLI：适合自动化脚本集成，支持丰富的命令行参数定制。

工作流详解

1. 参考阶段 (Optional)：若提供 --reference-epub，提取前作的译名表和风格提示。
2. 摘要阶段 (Summary)：串行生成每章摘要，构建全局上下文索引。
3. 翻译阶段 (Translation)：将章节切分为批次，在冻结的上下文中并发翻译。
4. 校对与重建 (Review & Rebuild)：对译文进行结构化校对，低分重试，最后将译文回写至原 EPUB 结构生成新书。

快速开始

1. 环境准备

推荐 Python 3.9+，使用 uv 管理依赖：

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

2. 配置环境变量

支持 DeepSeek、阿里云 DashScope、OpenAI Compatible 等接口。

# 示例：使用阿里云 Qwen-Max
export EPUB_TSUYAKU_API_KEY=your_api_key
export EPUB_TSUYAKU_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export EPUB_TSUYAKU_MODEL=qwen-max

3. 启动 Web UI (推荐)

uv run --python .venv/bin/python webui.py

访问 http://127.0.0.1:7860，即可上传 EPUB、选择模型、调整参数并实时监控翻译进度。

4. CLI 命令行示例

# 基础翻译
uv run --python .venv/bin/python main.py \
  --input testBook/book.epub \
  --source-lang 日语 \
  --target-lang 中文

# 带前作参考的高级翻译
uv run --python .venv/bin/python main.py \
  --input book_vol2.epub \
  --reference-epub book_vol1.zh.epub \
  --source-lang 日语 \
  --target-lang 中文 \
  --model qwen-max

适用场景

• 轻小说/网文汉化：对上下文连贯性和术语一致性要求极高的长篇作品。
• 系列作品翻译：需要继承前作译名和文风的多卷本电子书。
• 长任务处理：无法接受因网络波动或 API 限制导致任务中断重来的场景。
• 本地化测试：利用 --provider mock 模式离线调试流程，无需消耗 Token。

ePubTsuyaku 填补了通用 AI 翻译工具在处理复杂 EPUB 格式和长篇上下文时的空白。它通过工程化的手段，将“翻译”从一个简单的文本转换过程，升级为包含上下文管理、质量控制、风格继承和容错机制的系统工程。

对于个人汉化组、电子书爱好者或需要处理大量外文文献的研究者而言，ePubTsuyaku 提供了一个强大、灵活且可靠的本地化解决方案。立即尝试，让你的阅读体验跨越语言障碍！