BabelDOC 是一款专注于PDF科学文献翻译的工具，尤其擅长处理包含复杂公式、图表的学术论文，并支持生成双语对照的PDF文件。它主要通过命令行（CLI）和Python API使用，适合嵌入到其他工作流中。

本教程将指导你通过PyPI安装和源码安装两种方式进行部署，并介绍其核心使用方法。

📦 第一步：环境准备

BabelDOC 基于 Python 开发，官方推荐使用 uv 工具进行安装和管理。

  1. 安装 uv (如果尚未安装)：

    1
    2
    3
    4
    # macOS / Linux
    curl -LsSf https://astral.sh/uv/install.sh | sh
    # Windows (PowerShell)
    powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

    安装完成后，请确保 uv 已加入你的 PATH 环境变量。

  2. Python版本：BabelDOC 需要 Python 3.12 或兼容版本。uv 会自动管理所需的Python版本。

🚀 第二步：安装 BabelDOC

根据你的使用场景，推荐以下两种安装方式：

2.1 通过 PyPI 安装 (推荐终端用户)

这是最直接的方式，适合在终端中快速使用 babeldoc 命令。

1
2
3
4
5
# 使用 uv 工具安装 BabelDOC
uv tool install --python 3.12 BabelDOC

# 验证安装
babeldoc --help
  • 更新：如需更新到最新版本，可执行 uv tool upgrade BabelDOC。

2.2 从源码安装 (推荐开发者)

此方式适合需要修改代码、贡献或使用最新开发特性的用户。

1
2
3
4
5
6
7
# 1. 克隆仓库
git clone https://github.com/funstory-ai/BabelDOC.git
cd BabelDOC

# 2. 使用 uv 运行，无需显式激活虚拟环境
# 此命令会自动安装所有依赖
uv run babeldoc --help
  • 注意：使用 uv run babeldoc 前缀来执行所有命令。

⚙️ 第三步：基本翻译命令

BabelDOC 的核心功能是翻译 PDF 文档。它依赖 OpenAI 兼容的 API 进行翻译（这是当前主力方式）。

3.1 基本翻译示例

以下命令将使用 gpt-4o-mini 模型（通过 OpenAI API）翻译 example.pdf 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 通过 PyPI 安装后
babeldoc --openai \
         --openai-model "gpt-4o-mini" \
         --openai-base-url "https://api.openai.com/v1" \
         --openai-api-key "你的API密钥" \
         --files example.pdf

# 从源码安装 (在项目目录下)
uv run babeldoc --files example.pdf \
                --openai \
                --openai-model "gpt-4o-mini" \
                --openai-base-url "https://api.openai.com/v1" \
                --openai-api-key "你的API密钥"

3.2 翻译多个文件或指定页面

1
2
3
4
5
6
7
8
# 翻译多个PDF
babeldoc --openai --openai-api-key "你的密钥" \
         --files example1.pdf --files example2.pdf

# 指定翻译页面（例如：第1,3,5-7页）
babeldoc --openai --openai-api-key "你的密钥" \
         --files example.pdf \
         --pages "1,3,5-7"

3.3 使用其他兼容模型

BabelDOC 支持任何 OpenAI 兼容的 API 端点。你可以轻松切换模型：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 使用 DeepSeek
babeldoc --openai \
         --openai-model "deepseek-chat" \
         --openai-base-url "https://api.deepseek.com/v1" \
         --openai-api-key "你的DeepSeek密钥" \
         --files example.pdf

# 使用本地 Ollama 服务 (无需有效API Key)
babeldoc --openai \
         --openai-model "qwen2.5:7b" \
         --openai-base-url "http://localhost:11434/v1" \
         --openai-api-key "dummy" \
         --files example.pdf

🔧 第四步：高级配置与常用选项

BabelDOC 提供了丰富的选项来精细控制翻译和输出。为避免在命令行输入过长参数，推荐使用 TOML 配置文件。

4.1 使用配置文件

创建一个配置文件（例如 config.toml），内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
[babeldoc]
# 基本设置
lang-in = "en"          # 源语言 (默认英文)
lang-out = "zh-CN"      # 目标语言 (简体中文)
qps = 5                 # API请求频率限制 (每秒查询数)
output = "/path/to/output" # 输出目录 (可选)

# 翻译服务设置
openai = true
openai-model = "gpt-4o-mini"
openai-base-url = "https://api.openai.com/v1"
openai-api-key = "你的API密钥"

# PDF处理选项 (按需调整)
skip-scanned-detection = false  # 若确定非扫描件，设为true可加速
max-pages-per-part = 30         # 超大文档分卷翻译，自动合并
use-alternating-pages-dual = false # 双语模式：false为左右对照，true为交替页面
watermark-output-mode = "watermarked" # 输出带水印版本

# 术语表 (可选)
# glossary-files = "/path/to/glossary.csv"

然后使用配置文件运行：

1
babeldoc --config config.toml --files example.pdf

4.2 关键选项说明

  • 语言设置：
    • --lang-in, -li: 源语言代码（默认 en）。
    • --lang-out, -lo: 目标语言代码（默认 zh）。当前主要针对英译中优化，已初步支持英译其他语言。
  • 输出控制：
    • --output, -o: 指定输出目录。
    • --no-dual: 不输出双语PDF（默认输出）。
    • --no-mono: 不输出纯译文PDF（默认输出）。
    • --use-alternating-pages-dual: 启用交替页面模式（一页原文，一页译文），而不是默认的左右对照模式。
  • 性能与兼容性：
    • --qps: 控制请求速率，避免API限流。
    • --pool-max-workers: 控制内部处理线程数。
    • --skip-scanned-detection: 如果你确定PDF是电子生成的，跳过扫描检测可显著加速。
    • --ocr-workaround: 实验性，为扫描版PDF（纯黑白背景）提供的OCR替代方案，会在译文下方添加白色背景遮盖原文。
    • --enhance-compatibility: 启用系列兼容性增强选项，在遇到渲染异常时可尝试。

🧩 第五步：离线部署与集成

5.1 生成离线资源包

在联网机器上生成包含所有模型和字体的离线包，用于内网环境：

1
babeldoc --generate-offline-assets /path/to/output/dir

这会生成一个如 offline_assets_<hash>.zip 的文件。

5.2 恢复离线资源包

在离线机器上，使用以下命令恢复资源：

1
2
3
babeldoc --restore-offline-assets /path/to/offline_assets_<hash>.zip
# 或提供目录，工具会自动查找
babeldoc --restore-offline-assets /path/to/dir

5.3 集成到其他工具

  • Zotero 插件：BabelDOC 可集成到 Zotero-pdf2zh 插件中使用。
  • Python API：BabelDOC 主要设计为被集成，其内部API可能变动。推荐的调用方式是使用上游项目 pdf2zh 的 high_level.do_translate_async_stream 函数。

🩺 第六步：常见问题与排障

  • PyMuPDF 或字体相关错误：确保系统已安装所需的字体。部分Linux环境需安装 fontconfig 和中文字体（如 fonts-noto-cjk）。
  • 翻译结果不佳或报错：检查API密钥和 base-url 是否正确。部分模型（如本地小模型）可能需要更具体的提示词，可尝试调整 --custom-system-prompt。
  • 输出PDF排版错乱：这是PDF解析的常见难点。可以尝试组合使用以下选项：
    • --enhance-compatibility
    • --disable-rich-text-translate
    • --skip-clean
    • --dual-translate-first
  • 速度很慢：降低 --qps 值，或使用更快的模型。对于大型文档，设置 --max-pages-per-part 进行分卷翻译。

⚠️ 重要说明

  • 开发状态：BabelDOC 仍处于早期开发阶段，部分功能（如表格、跨页段落支持）仍在完善中。反馈和贡献非常欢迎。
  • API 稳定性：所有 BabelDOC 的 Python API 均应视为内部接口，直接使用不被官方支持。推荐使用 CLI 或通过 pdf2zh 等上游项目调用。
  • 终端用户建议：对于非开发者，官方推荐直接使用 Immersive Translate - BabelDOC 在线服务（每月提供1000页免费额度）或 PDFMathTranslate 2.0 的 WebUI。

现在，你已经完成了 BabelDOC 的部署和基础配置。开始使用它来高效处理你的学术文献吧！