funstory-ai/BabelDOC

PDF 科研论文翻译及双语对照库。 - **在线服务**：测试版已上线 [沉浸式翻译 - BabelDOC](https://app.immersivetranslate.com/babel-doc/) 提供免费使用额度，详情请参阅页面上的常见问题解答部分。 - **私有化部署**：[PDFMathTranslate-next](https://github.com/PDFMathTranslate-next/PDFMathTranslate-next) 支持 BabelDOC，可用于私有化部署 + WebUI，并提供更多翻译服务。 - 提供简单的 [命令行接口](#getting-started)。 - 提供 [Python API](#python-api)。 - 主要设计用于嵌入到其他程序中，但也可直接用于简单的翻译任务。 [支持的语言](https://funstory-ai.github.io/BabelDOC/supported_languages/) ## 预览 ## 我们在招聘 查看详情：[英文](https://github.com/funstory-ai/jobs) | [中文](https://github.com/funstory-ai/jobs/blob/main/README_ZH.md) ## 快速开始 ### 从 PyPI 安装 我们推荐使用 [uv](https://github.com/astral-sh/uv) 的 Tool 功能来安装 yadt。 1. 首先，您需要参考 [uv 安装说明](https://github.com/astral-sh/uv#installation) 安装 uv，并按照提示设置 `PATH` 环境变量。 2. 使用以下命令安装 yadt： ``` uv tool install --python 3.12 BabelDOC babeldoc --help ``` 3. 使用 `babeldoc` 命令。例如： ``` babeldoc --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here" --files example.pdf # 多个文件 babeldoc --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here" --files example1.pdf --files example2.pdf ``` ### 从源码安装 我们依然推荐使用 [uv](https://github.com/astral-sh/uv) 来管理虚拟环境。 1. 首先，您需要参考 [uv 安装说明](https://github.com/astral-sh/uv#installation) 安装 uv，并按照提示设置 `PATH` 环境变量。 2. 使用以下命令安装 yadt： ``` # 克隆项目 git clone https://github.com/funstory-ai/BabelDOC # 进入项目目录 cd BabelDOC # 安装依赖并运行 babeldoc uv run babeldoc --help ``` 3. 使用 `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" # 多个文件 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`：禁用富文本翻译（可能有助于提高某些 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） - `--formular-font-pattern`：用于识别公式文本的字体模式（默认：None） - `--formular-char-pattern`：用于识别公式文本的字符模式（默认：None） - `--show-char-box`：显示字符边界框（仅用于调试，默认：False） - `--skip-scanned-detection`：跳过扫描文档检测（默认：False）。使用拆分翻译时，如果未跳过，则仅第一部分执行检测。 - `--ocr-workaround`：使用 OCR 替代方案（默认：False）。仅适用于白底黑字的文档。启用后，将在翻译下方添加白色矩形块以覆盖原始文本内容，并强制将所有文本设置为黑色。 - `--auto-enable-ocr-workaround`：启用自动 OCR 替代方案（默认：False）。如果检测到文档被大量扫描，这将尝试启用 OCR 处理并跳过进一步的扫描检测。有关其与 `--ocr-workaround` 和 `--skip-scanned-detection` 交互的关键细节，请参阅下方的“重要交互说明”。 - `--primary-font-family`：覆盖翻译文本的主要字体族。选项：'serif' 表示衬线字体，'sans-serif' 表示无衬线字体，'script' 表示手写体/斜体。如果未指定，则使用基于原始文本属性的自动字体选择。 - `--only-include-translated-page`：输出 PDF 中仅包含已翻译的页面。此选项仅在启用 `--pages` 时有效。（默认：False） - `--merge-alternating-line-numbers`：启用后处理以合并交替的行号布局（将数字段落保留为独立段落 b；当 `layout_id` 和 `xobj_id` 匹配时，合并其两侧相邻的文本段落 a 和 c，且数字仅为 ASCII 和空格）。默认：关闭。 - `--skip-form-render`：跳过表单渲染（默认：False）。启用后，PDF 表单将不会在输出中渲染。 - `--skip-curve-render`：跳过曲线渲染（默认：False）。启用后，PDF 曲线将不会在输出中渲染。 - `--only-parse-generate-pdf`：仅解析 PDF 并生成输出 PDF 而不进行翻译（默认：False）。这将跳过所有与翻译相关的处理，包括布局分析、段落查找、样式处理以及翻译本身。适用于测试 PDF 解析和重建功能。 - `--remove-non-formula-lines`：移除段落区域中的非公式线条（默认：False）。这将移除不属于公式的装饰性线条，同时保护图/表区域中的线条。适用于清理带有干扰文本流的装饰性元素的文档。 - `--non-formula-line-iou-threshold`：移除非公式线条时用于检测段落重叠的 IoU 阈值（默认：0.9）。值越高越保守，移除的线条越少。 - `--figure-table-protection-threshold`：移除非公式线条时保护图/表区域中线条的 IoU 阈值（默认：0.9）。值越高，对图和表中结构元素的保护越强。 - `--rpc-doclayout`：用于文档布局分析的 RPC 服务主机地址（默认：None） - `--working-dir`：用于翻译的工作目录。如果未设置，则使用临时目录。 - `--no-auto-extract-glossary`：禁用自动术语提取。如果存在此标志，则跳过该步骤。默认启用。 - `--save-auto-extracted-glossary`：将自动提取的术语表保存到指定文件。如果未设置，则不保存术语表。 ### 翻译服务选项 - `--qps`：翻译服务的 QPS（每秒查询数）限制（默认：4） - `--ignore-cache`：忽略翻译缓存并强制重新翻译 - `--no-dual`：不输出双语 PDF 文件 - `--no-mono`：不输出单语 PDF 文件 - `--min-text-length`：要翻译的最小文本长度（默认：5） - `--openai`：使用 OpenAI 进行翻译（默认：False） - `--custom-system-prompt`：用于翻译的自定义系统提示词。 - `--add-formula-placehold-hint`：为翻译添加公式占位符提示。（目前不推荐，可能会影响翻译质量，默认：False） - `--disable-same-text-fallback`：当 LLM 输出与输入文本匹配时，禁用回退翻译。（默认：False） - `--pool-max-workers`：内部任务处理池的最大工作线程数。如果未指定，则默认为 QPS 值。此参数直接设置工作线程数，取代了之前基于 QPS 的动态计算。 - `--no-auto-extract-glossary`：禁用自动术语提取。如果存在此标志，则跳过该步骤。默认启用。 ### OpenAI 特定选项 - `--openai-model`：要使用的 OpenAI 模型（默认：gpt-4o-mini） - `--openai-base-url`：OpenAI API 的 Base URL - `--openai-api-key`：OpenAI 服务的 API 密钥 - `--enable-json-mode-if-requested`：为 OpenAI 请求启用 JSON 模式（默认：False） - `--term-pool-max-workers`：专用于自动术语提取的最大工作线程数。如果未指定，则默认为 `--pool-max-workers` 的值，当后者未设置时默认为 QPS 值。 ### 术语表选项 - `--glossary-files`：以逗号分隔的术语表 CSV 文件路径。 - 每个 CSV 文件应包含以下列：`source`、`target` 和可选的 `tgt_lng`。 - `source` 列包含原始语言中的术语。 - `target` 列包含目标语言中的术语。 - `tgt_lng` 列（可选）指定特定条目的目标语言（例如，“zh-CN”、“en-US”）。 - 如果为条目提供了 `tgt_lng`，则仅当其（规范化的）`tgt_lng` 与 `--lang-out` 指定的（规范化的）总体目标语言匹配时，才会加载并使用该条目。规范化包括小写化以及将连字符（`-`）替换为下划线（`_`）。 - 如果未提供条目的 `tgt_lng`，则认为该条目适用于任何 `--lang-out`。 - 每个术语表的名称（在 LLM 提示词中使用）派生自其文件名（不含 .csv 扩展名）。 - 在翻译过程中，系统将根据加载的术语表检查输入文本。如果在当前文本片段中找到术语表中的术语，该术语表（包含相关术语）将包含在发给语言模型的提示词中，并附上要求遵守的指令。 ### 输出控制 - `--output`, `-o`：翻译文件的输出目录。如果未设置，则使用当前工作目录。 - `--debug`：启用调试日志级别，并将详细的中间结果导出到 `~/.cache/yadt/working`。 - `--report-interval`：进度报告间隔（以秒为单位，默认：0.1）。 ### 常规选项 - `--warmup`：仅下载并验证所需的资源，然后退出（默认：False） ### 离线资源管理 - `--generate-offline-assets`：在指定目录中生成离线资源包。这将创建一个包含所有必需模型和字体的 zip 文件。 - `--restore-offline-assets`：从指定文件还原离线资源包。这将从以前生成的包中提取模型和字体。 ### 配置文件 - `--config`, `-c`：配置文件路径。使用 TOML 格式。 配置示例： ``` [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" # Choices: "watermarked", "no_watermark", "both" max-pages-per-part = 50 # Automatically split the document for translation and merge it back. only_include_translated_page = false # Only include translated pages in the output PDF. Effective only when `pages` is used. # no-watermark = false # DEPRECATED: 改用 watermark-output-mode skip-scanned-detection = false # Skip scanned document detection for faster processing auto_extract_glossary = true # Set to false to disable automatic term extraction formular_font_pattern = "" # Font pattern for formula text formular_char_pattern = "" # Character pattern for formula text show_char_box = false # Show character bounding boxes (debug) ocr_workaround = false # Use OCR workaround for scanned PDFs rpc_doclayout = "" # RPC service host for document layout analysis working_dir = "" # Working directory for translation auto_enable_ocr_workaround = false # Enable automatic OCR workaround for scanned PDFs. See docs for interaction with ocr_workaround and skip_scanned_detection. skip_form_render = false # Skip form rendering (default: False) skip_curve_render = false # Skip curve rendering (default: False) only_parse_generate_pdf = false # Only parse PDF and generate output PDF without translation (default: False) remove_non_formula_lines = false # Remove non-formula lines from paragraph areas (default: False) non_formula_line_iou_threshold = 0.2 # IoU threshold for paragraph overlap detection (default: 0.2) figure_table_protection_threshold = 0.3 # IoU threshold for figure/table protection (default: 0.3) # 翻译服务 openai = true openai-model = "gpt-4o-mini" openai-base-url = "https://api.openai.com/v1" openai-api-key = "your-api-key-here" enable-json-mode-if-requested = false # Enable JSON mode when requested (default: false) disable_same_text_fallback = false # Disable fallback translation when LLM output matches input text (default: false) pool-max-workers = 8 # Maximum worker threads for task processing (defaults to QPS value if not set) # 术语表选项（可选） # glossary-files = "/path/to/glossary1.csv,/path/to/glossary2.csv" # 输出控制 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 目前在 Python 中调用 BabelDOC 的推荐方法是调用 [pdf2zh next](https://github.com/PDFMathTranslate/PDFMathTranslate-next) 的 `high_level.do_translate_async_stream` 函数。 ## 背景 有许多项目和团队正在努力使文档编辑和翻译变得更加容易，例如： - [mathpix](https://mathpix.com/) - [Doc2X](https://doc2x.noedgeai.com/) - [minerU](https://github.com/opendatalab/MinerU) - [PDFMathTranslate](https://github.com/funstory-ai/yadt) 还有一些解决该问题特定部分的解决方案，例如： - [layoutreader](https://github.com/microsoft/unilm/tree/master/layoutreader)：PDF 中文本块的阅读顺序 - [Surya](https://github.com/surya-is/surya)：PDF 的结构 本项目希望推动一个标准的 pipeline 和接口来解决这个问题。 事实上，PDF 解析器或翻译器主要分为两个阶段： - **解析**：解析阶段意味着获取 PDF 的结构，如文本块、图像、表格等。 - **渲染**：渲染阶段意味着将该结构渲染为新的 PDF 或其他格式。 对于像 mathpix 这样的服务，它会将 PDF 解析为可能是 XML 格式的结构，然后像 [layoutreader](https://github.com/microsoft/unilm/tree/master/layoutreader) 那样使用单列阅读顺序进行渲染。坏消息是原始结构会。 有些人会使用 Adobe PDF Parser，因为它会生成一个 Word 文档并保留原始结构。但它有点昂贵。 而且您也知道，PDF 或 Word 文档并不是在移动设备上阅读的好格式。 我们提供了解析器结果的中间表示，并且可以将其渲染为新的 PDF 或其他格式。该 pipeline 也是一个基于插件的系统，每个人都可以添加新的模型、OCR、渲染器等。 ## 路线图 - [ ] 添加线条支持 - [ ] 添加表格支持 - [ ] 添加跨页/跨栏段落支持 - [ ] 更高级的排版功能 - [ ] 大纲支持 - [ ] ... 我们第一个 1.0 版本的目标是完成从 [PDF Reference, Version 1.7](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.7old.pdf) 到以下语言版本的翻译： - 简体中文 - 繁体中文 - 日语 - 西班牙语 并满足以下要求： - 排版错误小于 1% - 内容丢失小于 1% ## 版本号说明 本项目结合使用 [语义化版本控制](https://semver.org/) 和 [骄傲版本控制](https://pridever.org/)。版本号格式为：“0.MAJOR.MINOR”。 - MAJOR：当进行 API 不兼容的更改或实现了令人自豪的改进时，增加 1。 - MINOR：当进行任何 API 兼容的更改时，增加 1。 ## 已知问题 1. 作者和参考文献部分的解析错误；它们在翻译后被合并为一个段落。 2. 不支持线条。 3. 不支持首字下沉。 4. 过大的页面将被跳过。 ## 鸣谢 - [PDFMathTranslate](https://github.com/Byaidu/PDFMathTranslate) - [DocLayout-YOLO](https://github.com/opendatalab/DocLayout-YOLO) - [pdfminer](https://github.com/pdfminer/pdfminer.six) - [PyMuPDF](https://github.com/pymupdf/PyMuPDF) - [Asynchronize](https://github.com/multimeric/Asynchronize/tree/master?tab=readme-ov-file) - [PriorityThreadPoolExecutor](https://github.com/oleglpts/PriorityThreadPoolExecutor)

Star 历史

标签：AI翻译, BabelDOC, Immersive Translate, PDF处理, PDF翻译, Petitpotam, Python, Python安全, 双语对比, 双语对照, 学术翻译, 开源, 文本翻译, 文档处理, 文档翻译, 无后门, 机器翻译, 沉浸式翻译, 科技论文, 翻译工具, 自部署, 论文翻译, 跨语言, 逆向工具