GitHub - funstory-ai/BabelDOC: 又一文档翻译工具

技术背景

当前有许多项目和团队致力于让文档编辑和翻译变得更简单，例如 mathpix、Doc2X、minerU、PDFMathTranslate 等。也有一些解决方案专注于解决特定问题，如 layoutreader 处理 PDF 中文本块的阅读顺序，Surya 处理 PDF 的结构。然而，现有的工具存在一些问题，如 mathpix 解析 PDF 后会丢失原始结构，Adobe PDF Parser 虽能保留结构但价格昂贵，且 PDF 或 Word 文档在移动设备上阅读体验不佳。BabelDOC 项目希望推动一个标准的流程和接口来解决这些问题，提供解析结果的中间表示，可渲染成新的 PDF 或其他格式，其流程是基于插件系统，用户可以添加新的模型、OCR、渲染器等。

实现步骤

安装方式

从 PyPI 安装

1. 参考 uv 安装说明安装 uv 并设置 PATH 环境变量。
2. 使用以下命令安装 yadt：uv tool install --python 3.12 BabelDOC
3. 使用 babeldoc --help 查看帮助信息，例如翻译单个文件：babeldoc --bing --files example.pdf，翻译多个文件：babeldoc --bing --files example1.pdf --files example2.pdf

从源码安装

1. 参考 uv 安装说明安装 uv 并设置 PATH 环境变量。
2. 克隆项目：git clone https://github.com/funstory-ai/BabelDOC
3. 进入项目目录：cd BabelDOC
4. 安装依赖并运行：uv run babeldoc --help
5. 例如翻译单个文件：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"，翻译多个文件：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"

高级选项使用

语言选项

• --lang-in, -li：源语言代码，默认是 en。
• --lang-out, -lo：目标语言代码，默认是 zh。

PDF 处理选项

• --files：输入 PDF 文档的一个或多个文件路径。
• --pages, -p：指定要翻译的页面，例如 "1,2,1-,-3,3-5"，未设置则翻译所有页面。
• --split-short-lines：强制将短行拆分为不同段落。
• --short-line-split-factor：拆分阈值因子，默认是 0.8。
• --skip-clean：跳过 PDF 清理步骤。
• --dual-translate-first：在双语 PDF 模式下先放置翻译页。
• --disable-rich-text-translate：禁用富文本翻译。
• --enhance-compatibility：启用所有兼容性增强选项。
• --use-alternating-pages-dual：在双语 PDF 中使用交替页面模式。
• --watermark-output-mode：控制水印输出模式，有 'watermarked'、'no_watermark'、'both' 可选。
• --max-pages-per-part：分割翻译时每部分的最大页数。
• --translate-table-text：翻译表格文本（实验性，默认 False）。
• --skip-scanned-detection：跳过扫描文档检测（默认 False）。
• --ocr-workaround：使用 OCR 解决方法（默认 False）。

翻译服务选项

• --qps：翻译服务的每秒查询限制，默认是 4。
• --ignore-cache：忽略翻译缓存并强制重新翻译。
• --no-dual：不输出双语 PDF 文件。
• --no-mono：不输出单语 PDF 文件。
• --min-text-length：要翻译的最小文本长度，默认是 5。
• --openai：使用 OpenAI 进行翻译（默认 False）。

OpenAI 特定选项

• --openai-model：要使用的 OpenAI 模型，默认是 gpt-4o-mini。
• --openai-base-url：OpenAI API 的基础 URL。
• --openai-api-key：OpenAI 服务的 API 密钥。

输出控制

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

离线资产管理

• --generate-offline-assets：在指定目录生成离线资产包。
• --restore-offline-assets：从指定文件恢复离线资产包。

配置文件

使用 --config, -c 指定配置文件路径，配置文件使用 TOML 格式，示例如下：

[babeldoc]
# Basic settings
debug = true
lang-in = "en-US"
lang-out = "zh-CN"
qps = 10
output = "/path/to/output/dir"

# PDF processing options
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"  # Choices: "watermarked", "no_watermark", "both"
max-pages-per-part = 50  # Automatically split the document for translation and merge it back.
# no-watermark = false  # DEPRECATED: Use watermark-output-mode instead
skip-scanned-detection = false  # Skip scanned document detection for faster processing

# Translation service
openai = true
openai-model = "gpt-4o-mini"
openai-base-url = "https://api.openai.com/v1"
openai-api-key = "your-api-key-here"

# Output control
no-dual = false
no-mono = false
min-text-length = 5
report-interval = 0.5

# Offline assets management
# Uncomment one of these options as needed:
# generate-offline-assets = "/path/to/output/dir"
# restore-offline-assets = "/path/to/offline_assets_package.zip"

核心代码

Python API 使用示例

from pathlib import Path
import babeldoc.assets.assets

# 生成离线资产包
babeldoc.assets.assets.generate_offline_assets_package(Path("/path/to/output/dir"))

# 从包文件恢复
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"))

最佳实践

• 对于大文档，使用 --max-pages-per-part 选项将其拆分为较小部分进行翻译并自动合并。
• 遇到兼容性问题时，先尝试使用 --enhance-compatibility 选项。
• 确定文档不是扫描 PDF 时，使用 --skip-scanned-detection 加快处理速度。
• 对于扫描 PDF，使用 --ocr-workaround 填充背景。
• 在生产环境中，建议预先生成离线资产包并包含在应用程序分发中。

常见问题

• 解析问题：作者和参考部分解析错误，翻译后会合并为一个段落。
• 功能不支持：不支持行、首字下沉。
• 页面处理：大页面会被跳过。