TranslateBooksWithLLMs命令行完全手册：一行命令批量翻译EPUB、DOCX与TXT

TranslateBooksWithLLMs命令行完全手册：一行命令批量翻译EPUB、DOCX与TXT

【免费下载链接】TranslateBooksWithLLMsTranslate full-length books and documents with Ollama, OpenAI-compatible, Gemini, Mistral, DeepSeek, Poe or OpenRouter. Preserves formatting. Resumes where you left off. No file size limits.项目地址: https://gitcode.com/gh_mirrors/tr/TranslateBooksWithLLMs

TranslateBooksWithLLMs（TBL）是一款开源的 AI 书籍翻译工具，支持通过命令行一行命令批量翻译EPUB、DOCX、TXT、SRT、PDF文件。基于translate.py入口脚本，你可以调用 Ollama、OpenAI、Gemini、Mistral、DeepSeek、Poe 或 OpenRouter 等模型提供商，翻译完整保留原文档排版，支持断点续翻、术语表锁定和二次润色，且没有任何文件大小限制——从单页文档到千页长篇小说都能处理。

本手册面向新手，带你从零跑通第一条翻译命令，到掌握多提供商切换、并行加速、术语表与 TTS 语音等全部 CLI 玩法。

📥 第一步：安装与环境准备

快速克隆仓库

git clone https://gitcode.com/gh_mirrors/tr/TranslateBooksWithLLMs cd TranslateBooksWithLLMs pip install -r requirements.txt

依赖清单见 requirements.txt，核心为 Flask、httpx、lxml、tiktoken 等；命令行翻译功能不依赖 Web 界面，只装 Python 依赖即可使用。

两种模型接入方式

首次运行前可用curl http://localhost:11434/api/tags测试 Ollama 是否正常运行，更多排查方法见 docs/TROUBLESHOOTING.md。

🚀 核心命令：一条命令完成整本书翻译

CLI 的完整定义位于 translate.py，最简用法只有一个必填参数-i：

# 翻译 EPUB 小说（自动生成 "novel (Chinese).epub"） python translate.py -i novel.epub -sl English -tl Chinese # 翻译 TXT / DOCX / SRT / PDF 同理 python translate.py -i book.txt -tl Chinese python translate.py -i report.docx -tl Chinese python translate.py -i movie.srt -tl Chinese

💡 不指定-o时，输出文件自动命名为{原文件名} ({目标语言}).{扩展名}；若文件已存在会自动追加编号，不会覆盖旧文件。

上图即 Web 界面中的「暂停翻译」面板：翻译中断后可精确续传，并支持中途更换模型——同样的检查点机制在命令行下同样生效。

⚙️ 常用参数速查表

基础参数

提示词增强选项

🌐 切换模型提供商：一行命令换引擎

本地 Ollama（默认，无需 Key）

python translate.py -i book.txt -m qwen3:14b

云端提供商示例

# OpenAI python translate.py -i book.txt --provider openai \ --openai_api_key sk-xxx -m gpt-4o -tl French # Gemini python translate.py -i book.txt --provider gemini \ --gemini_api_key xxx -m gemini-2.0-flash -tl French # DeepSeek python translate.py -i book.txt --provider deepseek \ --deepseek_api_key xxx -m deepseek-v4-pro -tl French # 任意 OpenAI 兼容服务器（llama.cpp、LM Studio、vLLM） python translate.py -i book.txt --provider openai \ --api_endpoint http://localhost:8080/v1/chat/completions -m your-model

🔑 多 API Key 自动轮换

任何--*_api_key参数都支持逗号分隔多个 Key，遇到 429 限流自动切换下一个——非常适合串联多个免费额度账号：

python translate.py -i book.txt --provider gemini \ --gemini_api_key key1,key2,key3 -m gemini-2.0-flash

详细机制见 docs/API_KEY_ROTATION.md，各提供商的 Key 获取方式见 docs/PROVIDERS.md。

📚 高级玩法：让翻译质量更上一层楼

术语表：全书专名一致

LLM 逐块翻译、块间无记忆，同一角色名可能在不同章节被译成不同写法。用--glossary注入 JSON 或 CSV 术语表，规则只会在术语实际出现的分块中注入，不浪费 token：

python translate.py -i novel.epub -sl Chinese -tl English \ --glossary my_glossary.json

不想手工建表？加--auto-glossary --auto-style，工具会各花一次额外 LLM 调用从文档本身自动派生术语表和文风指令，无需任何文件：

python translate.py -i novel.epub -sl Chinese -tl English --auto-glossary --auto-style

术语表的完整格式、名词性别标注等高级特性见 docs/GLOSSARY.md。

并发加速：--parallel

云端提供商下用--parallel同时翻译多个分块可显著提速；本地 Ollama 会自动强制为 1（单实例串行）。值越大越快，但可能触发限流：

python translate.py -i long_novel.epub -tl Chinese --parallel 4

🎧 TTS：翻译完直接生成有声书

# 自动按目标语言选音色 python translate.py -i book.txt -tl French --tts # 指定音色、格式与语速 python translate.py -i book.txt -tl French \ --tts --tts-voice fr-FR-DeniseNeural --tts-format mp3 --tts-rate "+10%"

TTS 基于 Edge-TTS，支持opus/mp3输出，详见 TTS 选项分组（translate.py）。

⚡ 关键机制：断点续翻与自动检查点

翻译长书时最担心的是中途断网、限流或停电。TBL 内置检查点系统（src/persistence/checkpoint_manager.py）自动保存进度，重新运行同一条命令即可从上次中断处继续，已完成的分块不会重复消耗 token。

若中途发现当前模型翻得不好，可在 Web 界面暂停任务后直接「Change model」换模型续翻（见文首截图）；命令行下同样只需重新执行命令即可续传。

🧾 .env 配置：一次设置，长期免参数

不想每次手敲参数？在项目根目录创建.env文件即可固化默认值，完整模板见 docs/CLI.md：

# 提供商与模型 LLM_PROVIDER=ollama DEFAULT_MODEL=qwen3:14b API_ENDPOINT=http://localhost:11434/api/generate # 云端 Key（支持逗号分隔多 Key 轮换） GEMINI_API_KEY=... DEEPSEEK_API_KEY=... # 性能 MAX_TOKENS_PER_CHUNK=450 PARALLEL_TRANSLATIONS=1

配置项的加载逻辑位于 src/config.py。

✅ 批量翻译实战清单

把上面各节组合起来，就是一套完整的命令行工作流：

1. 安装：克隆仓库 +pip install -r requirements.txt
2. 试水：python translate.py -i sample.txt -tl Chinese（本地 Ollama 直接跑）
3. 换引擎：--provider openai --openai_api_key sk-xxx -m gpt-4o
4. 提质量：加--glossary terms.json --refine
5. 提速：云端加--parallel 4，多 Key 防限流
6. 出声：加--tts生成有声书

完整参数参考：docs/CLI.md｜排错指南：docs/TROUBLESHOOTING.md｜Docker 部署：docs/DOCKER.md

一行命令，千页长书，格式不丢、进度可续——这就是 TranslateBooksWithLLMs 命令行模式的全部价值。

【免费下载链接】TranslateBooksWithLLMsTranslate full-length books and documents with Ollama, OpenAI-compatible, Gemini, Mistral, DeepSeek, Poe or OpenRouter. Preserves formatting. Resumes where you left off. No file size limits.项目地址: https://gitcode.com/gh_mirrors/tr/TranslateBooksWithLLMs