豆包批量翻译器 (Doubao Batch Translator)

一个面向 Doubao/ARK 的高吞吐批量翻译工具，基于 Python asyncio，支持 ePub/Markdown/HTML/JSON 翻译、自动模型降级、每模型 RPM 限速与漏译修复闭环。

🚀 核心特性

架构特点

一核多壳设计: 核心AsyncTranslator提供统一翻译能力，外层处理器适配不同场景
快慢双车道并发 + 每模型限速: 自动分流到快车道/慢车道，并按模型 RPM 精确限流
- 🐢 慢车道：doubao-seed-translation-250915 (RPM=5000, 免费额度)
- 🚀 快车道：DeepSeek, Doubao Pro 等 (RPM=30000, 高性能)
异步并发: 基于asyncio的高效异步处理，支持高并发翻译
模块化设计: 各功能模块独立，便于维护和扩展
智能降级: 采用"乐观尝试 + 优雅降级"策略，seed 模型失败自动切换快车道

📁 项目结构

doubao-batch-translator/
├── main.py                    # 主入口文件
├── pyproject.toml             # 项目依赖与元数据
├── uv.lock                    # uv 锁文件
├── .python-version            # Python 版本声明
├── README.md                  # 项目说明文档
├── models.json                # 模型配置
├── model_rate_limits.json     # 每模型 RPM 限速配置
├── .env.example               # 环境变量示例
│
├── core/                      # 核心模块
│   ├── client.py              # 异步翻译客户端
│   ├── config.py              # 配置管理
│   ├── exceptions.py          # 自定义异常
│   └── token_tracker.py       # Token配额跟踪
│
├── processors/                # 处理器模块
│   ├── json_worker.py         # JSON文件处理器
│   ├── html_worker.py         # HTML文件处理器
│   ├── epub_worker.py         # ePub电子书处理器
│   └── md_worker.py           # Markdown文件处理器
│
├── server/                    # HTTP服务器模块
│   └── api.py                 # API服务实现
│
├── tools/                     # 工具脚本
│   ├── check_untranslated.py  # EPUB漏译检测
│   ├── patch_leaks.py         # 漏译精准修复
│   ├── clean_xml.py           # XML清理工具
│   ├── manual_fix_epub.py     # EPUB手动精修助手
│   ├── export_ark_models.py   # 导出 ARK 模型清单与能力参数
│   └── capture_model_plaza_api.py  # 抓取控制台模型广场 XHR/FETCH JSON
│
├── tests/                     # 测试脚本
│   ├── test_concurrency.py    # 并发测试
│   ├── test_best_practices.py # 回归测试（语言参数、并发、API异常）
│   └── test_export_ark_models.py # 模型导出脚本测试
│
├── docs/                      # 文档
│   ├── CONCURRENCY_OPTIMIZATION.md
│   ├── EPUB_TRANSLATION_GUIDE.md
│   └── ...
│
└── logs/                      # 日志目录

📋 环境要求

Python: 3.13+
操作系统: Linux, macOS, Windows

📦 安装使用

1. 安装依赖

# 克隆项目
git clone <repository-url>
cd doubao-batch-translator

# 如未安装 uv，请先参考官方安装说明：
# https://docs.astral.sh/uv/getting-started/installation/

# 项目默认使用 CERNET PyPI 镜像；如需覆盖，可自行设置 UV_DEFAULT_INDEX

# 创建虚拟环境并安装依赖
uv sync --dev

2. 配置API密钥

# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，设置API密钥
# ARK_API_KEY=your_api_key_here

3. 基本使用

JSON文件翻译 (RenPy翻译专用)

# 基本用法
uv run python main.py json --file <your_json_file_path>

HTML文件翻译

# 基本用法 (默认翻译成中文)
uv run python main.py html --file <your_html_file_path> --output translated.html

ePub电子书翻译

# 单本翻译 (默认翻译成中文)
uv run python main.py epub --file <your_epub_file_path> --output translated.epub

# 批量翻译整个目录 (推荐)
uv run python main.py epub --file /path/to/epub/folder/ --output /path/to/output/ --auto-approve

Markdown文件翻译

# 基本用法 (默认翻译成中文)
uv run python main.py md --file README.md --output README_zh.md

# 翻译整个目录下的Markdown文件
uv run python main.py md --file /path/to/md/folder --output /path/to/output/folder

# 递归翻译目录下所有Markdown文件（包括子目录）
uv run python main.py md --file /path/to/md/folder --output /path/to/output/folder --recursive

# 使用简写参数
uv run python main.py md -f /path/to/md/folder -o /path/to/output/folder -r

# 翻译到其他语言
uv run python main.py md --file README.md --output README_en.md --target-lang en

特性:

✅ 代码块和行内代码保持不变
✅ 链接URL保持不变，仅翻译链接文本
✅ YAML Frontmatter 智能处理（仅翻译 title、description、summary 等字段）
✅ 支持批量翻译整个目录
✅ 支持递归翻译子目录中的文件
✅ 自动根据目标语言生成文件名后缀（如 _zh, _en, _ja 等）

🔄 人工翻译工作流 (新功能)

批量翻译完成后，如果仍有漏译，系统会自动生成 人工翻译.json 供您手动补充：

# 步骤1: 批量翻译 (自动生成漏译报告和JSON，默认翻译成中文)
uv run python main.py epub --file /path/to/books/ --output /path/to/translated/ --auto-approve

# 步骤2: (可选) 如果需要重新生成JSON
uv run python main.py generate-json --dir /path/to/translated/

# 步骤3: 编辑 人工翻译.json，填写您的译文

# 步骤4: 将人工译文回填到EPUB
uv run python main.py apply-fix --json /path/to/translated/人工翻译.json

JSON 格式示例:

{
  "books": [
    {
      "epub_name": "book_translated.epub",
      "segments": [
        {
          "original": "Untranslated text...",
          "translation": ""  // ← 在这里填写您的译文
        }
      ]
    }
  ]
}

🧭 模型清单导出与模型广场抓取

如果你想查看 Ark Runtime 可见模型及其参数（例如 token 限制、结构化输出、函数调用、批处理能力），可使用：

# 导出运行时模型列表（JSON）
uv run python tools/export_ark_models.py --active-only --pretty --output ark_models.json

# 导出为 CSV，便于筛选和排序
uv run python tools/export_ark_models.py --format csv --output ark_models.csv

# 仅看文本生成类模型
uv run python tools/export_ark_models.py --task-type TextGeneration --format md --output ark_models.md

如果你要抓取「火山引擎控制台模型广场」里更细的参数（通常需要登录态）：

# 首次使用按需拉起临时 Playwright 环境
uv run --with playwright playwright install chromium

# 打开浏览器并捕获模型广场相关 XHR/FETCH 返回
uv run --with playwright python tools/capture_model_plaza_api.py --wait-seconds 90 --output-dir model_plaza_capture

脚本会输出：

index.json: 全部捕获响应索引
model_candidates.json: 疑似模型列表接口的候选索引
*.json: 每条接口响应原始 JSON

启动HTTP API服务器

# 基本启动
uv run python main.py server --port 8000

# 调试模式
uv run python main.py server --port 8000 --debug

5. 🌐 沉浸式翻译插件配置

本项目提供 HTTP API 服务，可与沉浸式翻译浏览器插件配合使用，让你在浏览网页时直接使用豆包专用翻译模型。

启动服务器

uv run python main.py server --port 8000

服务器启动后会监听 http://0.0.0.0:8000。

配置方式一：OpenAI 兼容模式（推荐）

打开沉浸式翻译设置 → 翻译服务 → 选择 OpenAI
配置以下参数：
- API Key: 任意填写（如 sk-xxx，服务器不验证）
- 自定义 API 地址: http://127.0.0.1:8000/v1/chat/completions
- 模型: doubao-seed-translation-250915
重要：Prompt 配置
- System Prompt: 可留空（专用翻译模型不需要）
- Prompt: 填写 {{text}}（必须包含这个变量）
- Multiple Prompt: 填写 {{text}}
- Subtitle Prompt: 填写 {{text}}

配置方式二：自定义 API 模式

打开沉浸式翻译设置 → 开发者设置 → 启用 Beta 测试功能
翻译服务 → 选择 自定义 API
设置 URL: http://127.0.0.1:8000/translate

支持的语言代码（复制到沉浸式翻译配置）:

zh-CN,zh-TW,en,ja,ko,de,fr,es,it,pt,ru,th,vi,ar,cs,da,fi,hr,hu,id,ms,nl,pl,ro,sv,tr,uk,no

语言代码自动转换：服务器会自动将沉浸式翻译的语言代码转换为 Doubao API 支持的格式：

zh-CN → zh (简体中文)

zh-TW → zh-Hant (繁体中文)

auto → 空字符串 (自动检测)

no → nb (挪威语)

不支持的语言会降级为自动检测

请求格式（插件自动处理）:

{
  "source_lang": "en",
  "target_lang": "zh-CN",
  "text_list": ["Hello", "World"]
}

响应格式:

{
  "translations": [
    {"detected_source_lang": "en", "text": "你好"},
    {"detected_source_lang": "en", "text": "世界"}
  ]
}

API 端点说明

端点	方法	说明
`/`	GET	健康检查
`/v1/models`	GET	获取可用模型列表
`/v1/chat/completions`	POST	OpenAI 兼容翻译接口
`/translate`	POST	沉浸式翻译自定义 API 接口

常见问题

Q: 所有内容都被翻译成 "OK"？
A: 检查 Prompt 配置，确保包含 {{text}} 变量。如果 Prompt 为空，messages 会是空数组。

Q: 出现 422 错误？
A: 确认使用正确的端点。OpenAI 模式用 /v1/chat/completions，自定义 API 模式用 /translate。

Q: 连接被拒绝？
A: 确保服务器正在运行，使用 127.0.0.1 而不是 0.0.0.0 作为客户端地址。

配置方式三：直接对接火山方舟 API（无需中间服务器）

你可以直接在沉浸式翻译中配置火山方舟 API，无需使用本项目提供的中间服务器。这种方式更轻量，适合不需要批量翻译功能的用户。

配置步骤

打开沉浸式翻译设置 → 翻译服务 → 点击 Edit Full User Config
在 translationServices 对象中添加或修改以下配置：

"custom-ai-d2JnahaZ": {
  "type": "custom-ai",
  "extends": "custom-ai",
  "name": "Doubao Seed Translation",
  "APIKEY": "你的 APIKey",
  "apiUrl": "https://ark.cn-beijing.volces.com/api/v3/responses",
  "model": "doubao-seed-translation-250915",
  "group": "custom",
  "visible": true,
  "limit": "80",
  "maxTextLengthPerRequest": "1000", // 按照模型最大输入Token设定
  "maxTextGroupLengthPerRequest": "1", // 每次只支持翻一个text
  "maxTextGroupLengthPerRequestForSubtitle": "1",
  "prompt": "{{text}}", // 必填，占位符
  "systemPrompt": "",
  "multiplePrompt": "{{text}}",
  "subtitlePrompt": "{{text}}",
  "headerConfigs": {
    "Authorization": "Bearer {{APIKEY}}",
    "Content-Type": "application/json"
  },
  "bodyConfigs": {
    "model": "doubao-seed-translation-250915",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "{{text}}",
            "translation_options": {
              "target_language": "{{to}}"
            }
          }
        ]
      }
    ]
  }
}

如果你希望显式指定 source_language，可以在 translation_options 中添加 "source_language": "{{from}}"。

保存配置后，选择 Doubao Seed Translation 作为当前翻译服务

功能验证方法

打开任意网页
确保已切换到「Doubao Seed Translation」为当前翻译服务
打开 DevTools → network 观察请求结构是否如下：

POST https://ark.cn-beijing.volces.com/api/v3/responses

{
  "model": "doubao-seed-translation-250915",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Hello world",
          "translation_options": {
            "target_language": "zh"
          }
        }
      ]
    }
  ]
}

问题排查清单

问题	原因	解决方法
翻译失败或未调用	Body格式不符，或没带 header	使用上面的 bodyConfig 与 headerConfig 模板
多段落被截断或失败	模型不支持聚合段落	设置 `"maxTextGroupLengthPerRequest": "1"`
输出断行、排版偏移	CSS 被原网页强制	用 `globalStyles` 加 `-webkit-line-clamp: unset;`
插件未调用你自定义服务	translationService 名填错	确保 `"translationService": "custom-ai-d2JnahaZ"`

进阶功能拓展建议（可选）

匹配特定语言自动使用翻译模型

"translationLanguagePattern": {
  "matches": ["en", "ja"]
}

显示主题样式

"translationTheme": "underline"

或者为不同网站设置：

"translationThemePatterns": {
  "highlight": {
    "matches": ["microsoft.com"]
  }
}

避免未配置项出现在 UI 面板中

"showUnconfiguredTranslationServiceInPopup": false,

绑定使用该服务用于全部网页或特定网页

"translationUrlPattern": {
  "matches": [ "*" ] // 或指定网站如 "twitter.com"
}

4. Token配额管理

每日2M免费额度监控: 实时跟踪token使用量，防止超额
断点续传: 支持翻译进度保存，中断后可继续

🔧 详细配置

命令行参数

通用参数

--api-key: API密钥（可选，默认从环境变量读取）
--verbose, -v: 启用详细日志
--max-concurrent: 最大并发请求数（默认: 20）
--max-rps: 每秒最大请求数（默认: 10.0）

JSON翻译参数

--file, -f: 输入文件（必需）
--output, -o: 输出文件
--source-lang: 源语言
--target-lang, -t: 目标语言（默认: zh）

HTML翻译参数

--file, -f: 输入文件（必需）
--output, -o: 输出文件
--source-lang: 源语言
--target-lang, -t: 目标语言（默认: zh）

ePub翻译参数

--file, -f: 输入文件（必需）
--output, -o: 输出文件（必需）
--source-lang: 源语言
--target-lang, -t: 目标语言（默认: zh）

Markdown翻译参数

--file, -f: 输入文件或文件夹（必需）
--output, -o: 输出文件或文件夹
--source-lang: 源语言
--target-lang, -t: 目标语言（默认: zh）
--recursive, -r: 递归翻译文件夹中的所有Markdown文件

服务器参数

--host: 绑定地址（默认: 0.0.0.0）
--port, -p: 监听端口（默认: 8000）
--debug: 启用调试模式

环境变量配置

# API配置
export ARK_API_KEY=your_api_key

支持的语言

代码	语言名称	代码	语言名称
zh	中文（简体）	zh-Hant	中文（繁体）
en	英语	de	德语
fr	法语	es	西班牙语
it	意大利语	pt	葡萄牙语
ja	日语	ko	韩语
th	泰语	vi	越南语
ru	俄语	ar	阿拉伯语

支持的模型

🐢 慢车道模型 (RPM=5000, 80并发)

适用于免费额度使用、稳定翻译场景

模型ID	特点	推荐场景
`doubao-seed-translation-250915`	免费额度、稳定可靠	日常翻译、免费使用

🚀 快车道模型 (RPM=30000, 500并发)

适用于大批量、高并发翻译场景

模型ID	特点	推荐场景
`deepseek-v3-250324`	高性能、低成本	大批量文档翻译
`deepseek-v3-1-terminus`	高性能	大批量文档翻译
`doubao-seed-1-6-lite-251015`	轻量快速	实时翻译
`doubao-seed-1-6-251015`	高性能	批量处理
`doubao-1-5-vision-pro-32k-250115`	视觉能力、大上下文	图文混合翻译
`doubao-1.5-vision-pro-250328`	视觉能力	UI文本翻译
`doubao-1.5-vision-lite-250315`	轻量视觉	快速图文翻译
`doubao-1-5-ui-tars-250428`	UI优化	界面文本翻译

配置方式: 编辑 models.json 文件，将需要使用的模型按优先级排列

[
  "doubao-seed-translation-250915",  // 优先使用免费额度
  "deepseek-v3-250324",              // 备用快车道
  "doubao-seed-1-6-251015"           // 备用快车道
]

系统会自动根据模型类型选择并发策略，并结合 model_rate_limits.json / MODEL_RPM_OVERRIDES 做每模型 RPM 限速。详见 CONCURRENCY_OPTIMIZATION.md

🔄 断点续传机制

JSON处理器

自动检测未翻译条目
每批翻译完成后立即保存结果
创建时间戳备份文件
支持中断后继续翻译

🛠️ 架构设计

核心组件

AsyncTranslator

职责: 统一翻译能力
特性: 异步并发、批处理、频率控制、重试机制

实现功能

单请求高并发: 适配doubao-seed-translation-250915模型（不支持批量请求）
并发控制: 使用Semaphore限制最大并发数（默认20）
Token跟踪: 实时监控使用量，防止超过每日免费额度
智能批处理: 基于token使用量的动态批次大小调整
检查点系统: 每50个项目自动保存进度

📈 性能优化

并发控制

默认并发数: 20
频率限制: 避免触发API限制

🤝 贡献指南

开发环境设置

# 安装开发依赖
uv sync --dev

服务管理（Linux 系统）

使用 systemd 服务（推荐用于生产环境）

本项目提供了 systemd 服务配置，可实现开机自启和后台运行。

cd /home/louis/doubao-batch-translator

# 1. 给管理脚本添加执行权限
chmod +x service-management.sh

# 2. 安装并启动服务（包括开机自启）
./service-management.sh install

# 3. 验证服务状态
./service-management.sh status

# 4. 查看实时日志
./service-management.sh logs

常用管理命令

./service-management.sh start    # 启动服务
./service-management.sh stop     # 停止服务
./service-management.sh restart  # 重启服务
./service-management.sh enable   # 启用开机自启
./service-management.sh disable  # 禁用开机自启
./service-management.sh uninstall# 卸载服务

服务配置说明

服务文件：doubao-translator.service - systemd 服务配置
管理脚本：service-management.sh - 便捷的服务管理工具
环境变量：读取 .env 文件中的配置
日志：记录到 systemd journal，可通过 ./service-management.sh logs 查看

项目结构说明

详细的项目结构说明请参考 PROJECT_STRUCTURE.md 文件。

注意: 本工具专为高效利用豆包API的免费额度而设计，强烈建议在处理大型文件时监控翻译进度，确保符合每日额度限制。

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.claude/handoffs		.claude/handoffs
.github/workflows		.github/workflows
core		core
docs		docs
processors		processors
server		server
tests		tests
tools		tools
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
doubao-translator.service		doubao-translator.service
main.py		main.py
models.json		models.json
pyproject.toml		pyproject.toml
service-management.sh		service-management.sh
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

豆包批量翻译器 (Doubao Batch Translator)

🚀 核心特性

架构特点

📁 项目结构

📋 环境要求

📦 安装使用

1. 安装依赖

2. 配置API密钥

3. 基本使用

JSON文件翻译 (RenPy翻译专用)

HTML文件翻译

ePub电子书翻译

Markdown文件翻译

🔄 人工翻译工作流 (新功能)

🧭 模型清单导出与模型广场抓取

启动HTTP API服务器

5. 🌐 沉浸式翻译插件配置

启动服务器

配置方式一：OpenAI 兼容模式（推荐）

配置方式二：自定义 API 模式

API 端点说明

常见问题

配置方式三：直接对接火山方舟 API（无需中间服务器）

配置步骤

功能验证方法

问题排查清单

进阶功能拓展建议（可选）

4. Token配额管理

🔧 详细配置

命令行参数

通用参数

JSON翻译参数

HTML翻译参数

ePub翻译参数

Markdown翻译参数

服务器参数

环境变量配置

支持的语言

支持的模型

🐢 慢车道模型 (RPM=5000, 80并发)

🚀 快车道模型 (RPM=30000, 500并发)

🔄 断点续传机制

JSON处理器

🛠️ 架构设计

核心组件

AsyncTranslator

实现功能

📈 性能优化

并发控制

🤝 贡献指南

开发环境设置

服务管理（Linux 系统）

使用 systemd 服务（推荐用于生产环境）

常用管理命令

服务配置说明

项目结构说明

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages