BabelDOC：将PDF文档翻译成双语对照的开源工具

综合介绍

BabelDOC 是一个开源工具，专门用来把 PDF 文档翻译成双语对照格式。它由 funstory-ai 团队开发，托管在 GitHub 上，主要服务于需要处理外语文档的用户，比如研究人员、学生和技术人员。BabelDOC 支持将英文 PDF 翻译成中文，保留原文排版，包括数学公式和表格。用户可以通过在线服务、命令行工具（CLI）或 Python API 使用它。在线服务由 Immersive Translate 提供，每月免费 1000 页；自部署则可通过源码或 PDFMathTranslate 项目实现。

功能列表

• 将 PDF 文件翻译成双语对照格式，原文和译文并排显示。
• 保留原文排版，支持数学公式、表格和图片的正确呈现。
• 提供命令行工具（CLI），支持批量翻译多个文件。
• 提供 Python API，方便开发者嵌入到其他程序中。
• 支持在线服务，每月免费翻译 1000 页。
• 支持自部署，可选择本地运行或结合 PDFMathTranslate 使用更多翻译服务。
• 可配置多种翻译引擎，如 OpenAI、Bing 等。
• 提供离线资源包管理，适合无网络环境使用。

使用帮助

BabelDOC 的使用方式多样，包括在线服务和本地部署。以下是详细的操作指南，帮助你快速上手。

在线服务使用

1. 访问在线服务
   打开 Immersive Translate - BabelDOC，这是一个 Beta 版服务。
2. 上传文件
   点击上传按钮，选择需要翻译的 PDF 文件。文件大小和页数需在免费额度（1000 页/月）内。
3. 选择语言
   默认支持英文到中文翻译。上传后，系统会自动处理并生成双语对照 PDF。
4. 下载结果
   翻译完成后，点击下载按钮获取翻译后的文件。结果会保留原文和译文并排显示。

本地安装流程

BabelDOC 支持从 PyPI 安装或源码安装，推荐使用 uv 管理环境。

从 PyPI 安装

1. 安装 Python 和 uv
   确保系统有 Python 3.12 或更高版本。下载安装 uv，并配置环境变量。
2. 安装 BabelDOC
   在终端运行：

uv tool install --python 3.12 BabelDOC

3. 验证安装
   输入：

babeldoc --help

如果显示帮助信息，说明安装成功。

从源码安装

1. 克隆项目
   在终端运行：

git clone https://github.com/funstory-ai/BabelDOC
cd BabelDOC

2. 安装依赖
   使用 uv 安装依赖：

uv run pip install -r requirements.txt

3. 验证安装
   运行：

uv run babeldoc --help

看到帮助信息即表示成功。

离线资源配置

如果需要离线使用，可以管理资源包：

1. 生成资源包

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

生成的 zip 文件包含字体和模型。
2. 恢复资源包

babeldoc --restore-offline-assets /path/to/offline_assets_package.zip

资源会解压到默认路径 ~/.cache/babeldoc/assets/。

本地使用方法

命令行使用

1. 翻译单个文件
   假设有一个文件 example.pdf，用 OpenAI 翻译：

babeldoc --files example.pdf --openai --openai-model "gpt-4o-mini" --openai-api-key "你的API密钥"

输出文件会自动生成，如 example_translated.pdf。
2. 翻译多个文件
处理多个文件：

babeldoc --files example1.pdf --files example2.pdf --bing

3. 指定页面
   只翻译第 1、3-5 页：

babeldoc --files example.pdf --pages "1,3-5" --openai --openai-api-key "你的API密钥"

4. 调整语言
   默认英译中，若需其他语言：

babeldoc --files example.pdf --lang-in "en" --lang-out "fr" --openai --openai-api-key "你的API密钥"

Python API 使用

1. 基本翻译
   创建文件 translate.py：

from babeldoc.main import TranslationConfig, translate_document
config = TranslationConfig(
files=["example.pdf"],
lang_in="en",
lang_out="zh",
translator="openai",
openai_api_key="你的API密钥",
openai_model="gpt-4o-mini"
)
translate_document(config)

运行 python translate.py 即可翻译。
2. 离线资源管理

from pathlib import Path
from babeldoc.assets.assets import generate_offline_assets_package, restore_offline_assets_package
# 生成资源包
generate_offline_assets_package(Path("/path/to/output/dir"))
# 恢复资源包
restore_offline_assets_package(Path("/path/to/offline_assets_package.zip"))

特色功能操作

1. 双语对照
   翻译后的 PDF 会将原文和译文并排放置。比如英文在左，中文在右，方便对比。公式如 E=mc^2 会保留原文，旁边加译文说明。
2. 复杂文档支持
   支持数学公式和表格的识别与保留。翻译时不会破坏原始结构。
3. 灵活部署
   在线服务简单快捷，自部署支持更多自定义选项，如翻译引擎选择。

自部署增强

如果需要更多功能，可以使用 PDFMathTranslate：

1. 安装 PDFMathTranslate
   按照其 GitHub 说明安装，支持 WebUI 和更多翻译服务。
2. 结合 BabelDOC
   PDFMathTranslate 1.9.3+ 版本实验性支持 BabelDOC，可增强翻译能力。

注意事项

• 在线服务每月免费 1000 页，超出需付费。
• 本地部署需配置 API 密钥，如 OpenAI 密钥可从 OpenAI 官网 获取。
• 当前主要优化英译中，其他语言支持有限。
• 大文件建议用 --max-pages-per-part 分段处理。

应用场景

1. 学术研究
   研究人员拿到英文论文，用 BabelDOC 翻译成双语对照版，方便阅读和理解。
2. 技术文档翻译
   开发者翻译英文技术手册，保留代码和图表，直接用于工作。
3. 教育学习
   学生用它翻译外语教材，一边学语言一边掌握内容。

QA

1. 支持哪些文件格式？
   只支持 PDF，其他格式需先转为 PDF。
2. 在线服务和本地部署有什么区别？
   在线服务简单，每月免费 1000 页；本地部署需安装，但可自定义更多选项。
3. 翻译不准确怎么办？
   尝试更换翻译引擎（如从 Bing 换到 OpenAI）或调整模型。
4. 如何贡献代码？
   查看 CONTRIBUTING，活跃贡献者可获 Immersive Translate 会员。