BabelDOC：PDF科学论文翻译与双语对比库

BabelDOC：PDF科学论文翻译与双语对比库

BabelDOC是一个专注于PDF科学论文翻译与双语对比的库，具备在线服务和自部署能力，并提供命令行界面与Python API 。

一、获取方式

1.1 从PyPI安装

建议使用uv工具来安装BabelDOC。首先要安装uv并设置好PATH环境变量，之后使用以下命令进行安装：

1
uv tool install --python 3.12 BabelDOC

安装完成后可通过babeldoc --help查看使用帮助，例如翻译单个PDF文件：

1
babeldoc --bing  --files example.pdf

如需翻译多个文件：

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

1.2 从源码安装

同样推荐使用uv管理虚拟环境。先安装uv并设置环境变量，然后按以下步骤操作：

  1. 克隆项目：
1
git clone https://github.com/funstory-ai/BabelDOC
  1. 进入项目目录：
1
cd BabelDOC
  1. 安装依赖并运行：
1
uv run babeldoc --help

使用示例：

1
uv run babeldoc --files example.pdf --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here"

翻译多个文件示例：

1
uv run babeldoc --files example.pdf --files example2.pdf --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here"

建议使用文件的绝对路径。

二、高级选项

2.1 语言选项

  • --lang-in, -li：源语言代码，默认值为en。
  • --lang-out, -lo：目标语言代码，默认值为zh。目前项目主要专注于英中翻译，其他场景未经过全面测试，2025.3.1更新后添加了对基本英文目标语言的支持。

2.2 PDF处理选项

  • --files：输入PDF文档的一个或多个文件路径。
  • --pages, -p：指定要翻译的页面，如"1,2,1-,-3,3-5"，不设置则翻译所有页面。
  • --split-short-lines：强制将短行拆分为不同段落（可能导致排版问题和错误）。
  • --short-line-split-factor：拆分阈值因子，默认值为0.8，实际阈值为当前页面所有行的中位数长度乘以该因子。
  • --skip-clean：跳过PDF清理步骤，可能会使文件变大，但有助于提高与某些PDF阅读器的兼容性。
  • --dual-translate-first：在双PDF模式下将翻译后的页面放在前面，默认先显示原始页面，可提升与部分PDF阅读器的兼容性。
  • --disable-rich-text-translate：禁用富文本翻译，有助于提高与某些PDF的兼容性。
  • --enhance-compatibility：启用所有兼容性增强选项，等同于--skip-clean --dual-translate-first --disable-rich-text-translate。
  • --use-alternating-pages-dual：使用交替页面模式的双PDF，启用时原始页面和翻译页面交替排列，默认是并排显示。
  • --watermark-output-mode：控制水印输出模式，'watermarked'（默认）为给翻译后的PDF添加水印，'no_watermark'为不添加水印，'both'为输出有水印和无水印两个版本。
  • --max-pages-per-part：拆分翻译时每个部分的最大页数，不设置则不进行拆分，用于处理大文档。
  • --no-watermark：已弃用，使用--watermark-output-mode=no_watermark替代。
  • --translate-table-text：翻译表格文本，为实验性功能，默认False。
  • --skip-scanned-detection：跳过扫描文档检测，默认False，在使用拆分翻译时，若不跳过则仅对第一部分进行检测，已知文档非扫描PDF时可使用此选项加速处理。

2.3 翻译服务选项

  • --qps：翻译服务的每秒查询次数（QPS）限制，默认值为4。
  • --ignore-cache：忽略翻译缓存并强制重新翻译。
  • --no-dual：不输出双语PDF文件。
  • --no-mono：不输出单语PDF文件。
  • --min-text-length：要翻译的最小文本长度，默认值为5。
  • --openai：使用OpenAI进行翻译，默认False。目前仅支持OpenAI兼容的大语言模型（LLM），推荐使用与OpenAI兼容性强的模型，也可使用litellm访问多个模型。

2.3.1 OpenAI特定选项

  • --openai-model：使用的OpenAI模型，默认值为gpt-4o - mini。
  • --openai-base-url：OpenAI API的基础URL。
  • --openai-api-key：OpenAI服务的API密钥，此工具支持任何OpenAI兼容的API端点，对于本地模型如Ollama，可使用任意值作为API密钥。

2.4 输出控制

  • --output, -o：翻译文件的输出目录，不设置则使用当前工作目录。
  • --debug, -d：启用调试日志级别，并在~/.cache/yadt/working中导出详细的中间结果。
  • --report-interval：进度报告间隔，单位为秒，默认值为0.1。

2.5 离线资产管理

  • --generate-offline-assets：在指定目录生成离线资产包，创建一个包含所有必需模型和字体的zip文件。
  • --restore-offline-assets：从指定文件恢复离线资产包，从先前生成的包中提取模型和字体。离线资产包适用于无网络环境或在多台机器上加速安装，生成的包名不能修改，因为文件列表哈希编码在名称中，恢复时若提供目录路径，工具会自动查找正确的离线资产包文件，包内资产完整性通过SHA3 - 256哈希验证，在空气隔绝环境部署时，需先在有网络的机器上生成包。

2.6 配置文件

可通过--config, -c指定配置文件路径，使用TOML格式。例如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
[babeldoc]
# 基本设置
debug = true
lang-in = "en-US"
lang-out = "zh-CN"
qps = 10
output = "/path/to/output/dir"

# PDF处理选项
split-short-lines = false
short-line-split-factor = 0.8
skip-clean = false
dual-translate-first = false
disable-rich-text-translate = false
use-alternating-pages-dual = false
watermark-output-mode = "watermarked"  # 选项: "watermarked", "no_watermark", "both"
max-pages-per-part = 50  # 自动拆分文档进行翻译并合并回来。
# no-watermark = false  # 已弃用: 使用watermark-output-mode替代
skip-scanned-detection = false  # 跳过扫描文档检测以加快处理速度

# 翻译服务
openai = true
openai-model = "gpt-4o-mini"
openai-base-url = "https://api.openai.com/v1"
openai-api-key = "your-api-key-here"

# 输出控制
no-dual = false
no-mono = false
min-text-length = 5
report-interval = 0.5

# 离线资产管理
# 根据需要取消注释以下选项之一:
# generate-offline-assets = "/path/to/output/dir"
# restore-offline-assets = "/path/to/offline_assets_package.zip"

三、Python API

在pdf2zh 2.0发布前，可暂时使用BabelDOC的Python API，但发布后建议直接使用pdf2zh的Python API，因为BabelDOC的Python API不保证兼容性，而pdf2zh的会保证一定兼容性。可参考main.py中的示例使用BabelDOC的Python API ，使用API前需调用babeldoc.high_level.init() ，且当前TranslationConfig不完全验证输入参数，需确保参数有效性。离线资产管理可使用以下函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from pathlib import Path
import babeldoc.assets.assets

# 生成离线资产包到特定目录
# path可选，默认是 ~/.cache/babeldoc/assets/offline_assets_{hash}.zip
babeldoc.assets.assets.generate_offline_assets_package(Path("/path/to/output/dir"))

# 从包文件恢复
# path可选，默认是 ~/.cache/babeldoc/assets/offline_assets_{hash}.zip
babeldoc.assets.assets.restore_offline_assets_package(Path("/path/to/offline_assets_package.zip"))

# 也可从包含离线资产包的目录恢复
# 工具会根据哈希自动找到正确的包文件
babeldoc.assets.assets.restore_offline_assets_package(Path("/path/to/directory"))

生产环境中建议预先生成资产包并包含在应用程序分发中，包验证可确保所有必需资产完整且与预期校验和匹配。

四、项目背景

当前有许多致力于简化文档编辑和翻译的项目与团队，如mathpix、Doc2X、minerU、PDFMathTranslate等，也有解决特定问题的方案，如layoutreader处理PDF文本块的阅读顺序，Surya处理PDF结构。BabelDOC希望推动一个标准的管道和接口来解决问题，PDF解析或翻译主要有两个阶段：解析（获取PDF结构，如文本块、图像、表格等）和渲染（将结构渲染成新的PDF或其他格式）。BabelDOC提供解析结果的中间表示，可渲染成新PDF或其他格式，其管道是基于插件的系统，便于添加新模型、OCR、渲染器等。

五、路线图

项目计划添加对行、表格、跨页/跨列段落的支持，实现更高级的排版功能和大纲支持等。首个1.0版本目标是完成从PDF Reference, Version 1.7到简体中文、繁体中文、日语、西班牙语的翻译，并满足布局错误小于1%、内容丢失小于1%的要求。

六、已知问题

  1. 作者和参考文献部分存在解析错误，翻译后会合并为一个段落。
  2. 不支持行。
  3. 不支持首字下沉。
  4. 大页面会被跳过。

七、如何贡献

鼓励对项目进行贡献，可查看CONTRIBUTING指南。参与项目的人员需遵循YADT行为准则，Immersive Translation为活跃贡献者提供每月Pro会员兑换码，详情见CONTRIBUTOR_REWARD.md。

软件开发 > 翻译工具开发
#Python #技术工具 #文档翻译 #开源项目
BabelDOC：PDF科学论文翻译与双语对比库
https://119291.xyz/posts/2025-04-15.babeldoc-pdf-scientific-paper-translation-and-bilingual-comparison-library/
作者
ww
发布于
2025年4月15日
许可协议