强大的 PDF 科学论文翻译工具BabelDOC

项目简介

预览

入门指南

从 PyPI 安装
我们推荐使用 uv 的 Tool 功能来安装 yadt。

1. 首先，您需要参考 uv 安装文档来安装 uv，并按照提示设置 PATH 环境变量。

2. 使用以下命令安装 yadt：

uv tool install --python 3.12 BabelDOC
babeldoc --help

1. Use the babeldoc command. For example:
   使用 babeldoc 命令。例如：

babeldoc --bing  --files example.pdf
# multiple filesbabeldoc --bing  --files example1.pdf --files example2.pdf

从源安装

我们仍然推荐使用 uv 来管理虚拟环境。

1. 首先，您需要参考 uv 安装说明来安装 uv，并按提示设置 PATH 环境变量。

2. 使用以下命令安装 yadt：

# clone the projectgit clone https://github.com/funstory-ai/BabelDOC
# enter the project directorycd BabelDOC
# install dependencies and run babeldocuv run babeldoc --help

1. 使用 uv run babeldoc 命令。例如：

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"
# multiple filesuv 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"

高级选项

PDF 处理选项

• --files: 输入 PDF 文档的文件路径之一或多个。
• --pages, -p:指定要翻译的页面（例如，“1,2,1-,-3,3-5”）。如未设置，则翻译所有页面
• --split-short-lines: 强制将短行拆分为不同的段落（可能会导致排版不佳和错误）
• --short-line-split-factor：实际阈值是当前页面上所有行的中位数长度乘以这个因子
• –skip-clean ：跳过 PDF 清理步骤
• –dual-translate-first : 将翻译的页面放在双 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 : 每部分最大页数以进行分割翻译。如果未设置，则不执行分割。
• –translate-table-text : 翻译表格文本（实验性，默认：False）

  
  

小贴士

• –skip-clean 和 --dual-translate-first 可能有助于提高某些 PDF 阅读器的兼容性
• –disable-rich-text-translate 也可以通过简化翻译输入来帮助兼容性
• 然而，使用 --skip-clean 将导致文件大小增加
• 如果您遇到任何兼容性问题，请首先尝试使用 --enhance-compatibility
• 使用 --max-pages-per-part 处理大文档，将其分割成更小的部分进行翻译，并自动合并回来。

翻译服务选项

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

1. 目前仅支持 OpenAI 兼容的LLM。如需更多翻译器支持，请使用 PDFMathTranslate。
2. 建议使用与 OpenAI 兼容性强的模型，例如： glm-4-flash ， deepseek-chat ，等等。
3. 目前尚未针对像 Bing/Google 这样的传统翻译引擎进行优化，建议使用LLMs。

OpenAI 特定选项
    --openai-model

•  : 要使用的 OpenAI 模型（默认：gpt-4o-mini）
• –openai-base-url : OpenAI API 的基础 URL
• –openai-api-key : OpenAI 服务的 API 密钥
  小贴士

1. 此工具支持任何与 OpenAI 兼容的 API 端点。只需设置正确的基本 URL 和 API 密钥即可。（例如： https://xxx.custom.xxx/v1 ）
2. 对于本地模型如 Ollama，您可以使用任何值作为 API 密钥（例如 --openai-api-key a ）。

输出控制

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

离线资源管理

• –generate-offline-assets : 在指定目录中生成离线资源包。这会创建一个包含所有必需模型和字体的 zip 文件。
• –restore-offline-assets : 从指定文件中恢复离线资源包。这会从先前生成的包中提取模型和字体。

  小贴士

1. 离线资源包对于没有互联网访问的环境或加快多台机器的安装速度非常有用。
2. 使用 babeldoc --generate-offline-assets /path/to/output/dir 生成一次包，然后分发。
3. 使用 babeldoc --restore-offline-assets /path/to/offline_assets_*.zip 在目标机器上恢复包。
4. 由于文件列表哈希值已编码在名称中，因此无法修改离线资源包的名称。
5. 如果您提供目录路径到 --restore-offline-assets ，该工具将自动在该目录中查找正确的离线资源包文件。
6. 该软件包包含文档处理所需的所有字体和模型，确保在不同环境中保持一致的结果。
7. 所有资产在打包和恢复过程中都使用 SHA3-256 散列进行验证。
8. 如果您在断网环境中部署，请确保首先在一台有互联网访问的机器上生成软件包。

配置文件

• –config , -c : 配置文件路径。使用 TOML 格式。

示例配置：

[babeldoc]# Basic settingsdebug = truelang-in = "en-US"lang-out = "zh-CN"qps = 10output = "/path/to/output/dir"
# PDF processing optionssplit-short-lines = falseshort-line-split-factor = 0.8skip-clean = falsedual-translate-first = falsedisable-rich-text-translate = falseuse-alternating-pages-dual = falsewatermark-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
# Translation serviceopenai = trueopenai-model = "gpt-4o-mini"openai-base-url = "https://api.openai.com/v1"openai-api-key = "your-api-key-here"
# Output controlno-dual = falseno-mono = falsemin-text-length = 5report-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"

扫码加入技术交流群，备注「开发语言-城市-昵称」

（文：GitHubStore）