企业官网建设流程全解析

BabelDOC 实战指南：基于 LLM 的 PDF 科学论文翻译与双语对照排版

【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC

BabelDOC（Yet Another Document Translator）是一个开源的 PDF 科学论文翻译与双语对照库，专注于"保留原始版式的 PDF 翻译"：解析 PDF 的文本块、图片、表格等结构后，借助 OpenAI 兼容的 LLM 完成翻译，再重新渲染为单语或双语 PDF。本文以官方 README 为主线，结合仓库源码（CLI 入口、TranslationConfig、翻译管线、术语表与资产管理等模块），完整讲解从安装、命令行翻译、全部高级参数到架构原理的实战细节，读完即可上手把一篇英文论文翻译成中英对照的 PDF。

项目概览与适用场景

BabelDOC 的核心定位是"PDF 科学论文翻译与双语对照库"，主要面向三类使用方式：

• 嵌入到其他程序中使用（官方主要设计目标），例如 Zotero 插件、自建 WebUI；
• 直接使用命令行工具完成简单翻译任务（babeldoc命令）；
• 调用 Python API（注意：BabelDOC 官方声明其所有 API 均为内部 API，直接使用不受支持，推荐通过 pdf2zh next 的high_level.do_translate_async_stream间接调用，见下文 Python API 一节）。

项目支持的语言范围可参考 docs/supported_languages.md：不依赖连字（ligature）的语言可获得良好支持，部分依赖连字的语言（如波兰语、法语、缅甸语）基本可满足自读需求，而完全依赖连字的语言（如部分印度语言）当前暂不支持，官方正在开发连字支持。注意 README 同时提示：当前项目主要聚焦英文到中文的翻译，其他语言场景尚未充分测试；2025.3.1 起补充了基础的英语目标语言支持，主要目的是最小化单词内部的换行（对应[0-9A-Za-z]+这类单词正则），更多语言的单词正则正在征集贡献。

仓库本身是只读研究资源，本文只介绍查看、安装、运行与配置方式。

安装

方式一：从 PyPI 安装（推荐）

官方推荐使用 uv 的 Tool 特性安装：

# 1. 先安装 uv 并按提示配置 PATH 环境变量 # 2. 安装 BabelDOC 并查看帮助 uv tool install --python 3.12 BabelDOC babeldoc --help

安装后即可使用babeldoc命令。项目在 pyproject.toml 中声明了babeldoc = "babeldoc.main:cli"作为命令行入口，Python 版本要求为>=3.10,<3.14，许可证为 AGPL-3.0。运行时依赖包含configargparse（参数与配置文件解析）、pymupdf（PDF 读写）、openai（LLM 调用）、onnxruntime（文档布局模型推理）、hyperscan（术语表高速匹配）等，可选依赖还提供cuda（onnxruntime-gpu）与directml等加速选项。

方式二：从源码安装

同样推荐用 uv 管理虚拟环境：

# clone 项目 git clone https://github.com/funstory-ai/BabelDOC cd BabelDOC # 安装依赖并运行 babeldoc uv run babeldoc --help

提示：无论哪种方式，官方都建议输入文件使用绝对路径。

首次运行时，BabelDOC 会通过 babeldoc/assets/assets.py 自动下载所需资产（文档布局 ONNX 模型、字体、CMap、tiktoken 缓存等），并使用 SHA3-256 哈希校验文件完整性；下载失败会按指数退避自动重试（最多 3 次）。

快速开始：命令行翻译

使用 OpenAI 兼容接口翻译单个 PDF：

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

一次翻译多个文件（重复传入--files）：

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 run babeldoc --files ... --openai ...。从 babeldoc/main.py 的实现看，命令行至少必须提供--openai翻译服务，且使用 OpenAI 服务时必须提供 API key，否则解析器会直接报错退出。

注意：README 明确说明，该 CLI 主要用于调试目的。虽然终端用户可以用它翻译文件，但官方不为此提供技术支持；终端用户应优先使用在线服务（Immersive Translate BabelDOC，每月有免费额度）或自行部署 PDFMathTranslate 2.0（提供 WebUI 和更多翻译服务）。README 中未列出的参数属于维护者专用的调试选项，请勿使用。

语言选项

两点提示（来自官方 README）：

1. 项目目前主要聚焦英译中，其他语言场景未经充分测试；
2. 2025.3.1 更新后加入了基础英语目标语言支持，主要用于最小化单词内部换行（[0-9A-Za-z]+），更多语言的单词正则表达式正在社区征集中。

翻译器的语言映射在 babeldoc/translator/translator.py 的BaseTranslator中完成（lang_map会做小写归一化），因此语言代码大小写不敏感。

PDF 处理选项

• --files：一个或多个输入 PDF 文档路径。
• --pages,-p：指定要翻译的页面，例如"1,2,1-,-3,3-5"；不设置则翻译全部页面。底层由 translation_config.py 的parse_pages解析为(start, end)区间列表（-1表示无上界），should_translate_page负责逐页判定。
• --split-short-lines：强制把短行拆分成不同段落（可能导致排版变差甚至出现 bug）。
• --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（两种都输出）。该枚举在 translation_config.py 中定义为WatermarkOutputMode。
• --max-pages-per-part：分拆翻译时每部分的最大页数；不设置则不分拆。大文档拆成多个小部分分别翻译后会自动合并回一份（见下文"分拆翻译"）。
• --no-watermark：已废弃，请改用--watermark-output-mode=no_watermark。
• --translate-table-text：翻译表格文字（实验性，默认False）。
• --formular-font-pattern/--formular-char-pattern：用于识别公式文本的字体模式 / 字符模式（默认None）。
• --show-char-box：显示字符包围框（仅调试，默认False）。
• --skip-scanned-detection：跳过扫描文档检测（默认False）。使用分拆翻译时，只有第一部分会执行检测。
• --ocr-workaround：OCR 变通方案（默认False）。仅适用于黑字白底的文档：启用后会在译文下方添加白色矩形块遮盖原文，并把所有文字强制为黑色。启用该选项会自动同时开启--skip-scanned-detection。
• --auto-enable-ocr-workaround：自动启用 OCR 变通（默认False）。若文档被检测为重度扫描件，将尝试开启 OCR 处理并跳过后续扫描检测。该参数与--ocr-workaround、--skip-scanned-detection存在重要交互，详见下文"重要交互说明"。
• --primary-font-family：覆盖译文主字体族，可选serif（衬线）、sans-serif（无衬线）、script（手写/斜体）；不指定时根据原文属性自动选字体。该取值在TranslationConfig中有显式断言校验。
• --only-include-translated-page：输出 PDF 中只包含翻译页，仅在配合--pages时有效（默认False）。
• --merge-alternating-line-numbers：启用"交替行号版式"后处理——当layout_id和xobj_id匹配、行号段为独立段落且内容仅为 ASCII 数字与空格时，合并其两侧的相邻文本段落（默认开启，可用--no-merge-alternating-line-numbers关闭）。
• --skip-form-render：跳过表单渲染（默认False）。
• --skip-curve-render：跳过曲线渲染（默认False）。
• --only-parse-generate-pdf：只解析 PDF 并生成输出 PDF、不翻译（默认False）。会跳过布局分析、段落查找、样式处理与翻译等全部翻译相关步骤，适合用来测试 PDF 解析与重建功能。此时管线会自动移除所有翻译阶段（见 high_level.py 的get_translation_stage）。
• --remove-non-formula-lines：移除段落区域中不属于公式的装饰性线条，同时保护图片/表格区域中的线条（默认False），用于清理干扰文本流的装饰元素。
• --non-formula-line-iou-threshold：移除非公式线条时，检测段落重叠的 IoU 阈值（默认0.9），值越大越保守、移除越少。
• --figure-table-protection-threshold：移除非公式线条时，保护图片/表格区域线条的 IoU 阈值（默认0.9），值越大对图/表结构元素保护越强。
• --rpc-doclayout：文档布局分析 RPC 服务地址（默认None）。从 main.py 看，还支持--rpc-doclayout2~--rpc-doclayout8等多个候选版本，按顺序回退；全部未设置时加载本地 ONNX 模型DocLayoutModel.load_onnx()。
• --working-dir：翻译工作目录；不设置则使用临时目录。
• --no-auto-extract-glossary：禁用自动术语提取（默认启用）；--save-auto-extracted-glossary：将自动提取的术语表保存到指定 CSV 文件（默认不保存）。

兼容性提示（官方 README）：

• --skip-clean与--dual-translate-first都可能提升部分 PDF 阅读器的兼容性；
• --disable-rich-text-translate通过简化翻译输入也能提升兼容性；
• 但使用--skip-clean会导致输出文件体积变大；
• 遇到兼容性问题，先尝试--enhance-compatibility；
• 大文档用--max-pages-per-part拆小后翻译再自动合并；
• 确认文档不是扫描件时用--skip-scanned-detection加速；
• 扫描 PDF 用--ocr-workaround填充背景（当前假设背景纯白、文字纯黑，且会自动启用--skip-scanned-detection）。

分拆翻译的底层机制

--max-pages-per-part的实现位于 high_level.py 的do_translate：通过SplitManager.determine_split_points计算切分点，为每个部分创建独立配置（part_config），将原 PDF 按页区间抽取为临时输入文件，逐部分串行翻译；其中只有第一部分执行扫描检测，只有第一部分输出带水印的 PDF，各部分的工作目录与输出目录隔离，最后通过ResultMerger.merge_results合并回完整文档。拆分策略由TranslationConfig.create_max_pages_per_part_split_strategy创建（对应 split_manager.py 的PageCountStrategy）。

翻译服务选项

• --qps：翻译服务每秒查询数（QPS）上限（默认4）。底层使用 translator.py 中基于漏桶算法、线程安全且使用单调时钟（monotonic time）的RateLimiter实现。
• --ignore-cache：忽略翻译缓存，强制重新翻译。默认情况下BaseTranslator.translate会先查 peewee 持久化缓存（TranslationCache），命中则直接返回。
• --no-dual：不输出双语 PDF。
• --no-mono：不输出单语 PDF。
• --min-text-length：参与翻译的最小文本长度（默认5）。
• --openai：使用 OpenAI 兼容接口翻译（默认False，为必选翻译服务）。
• --custom-system-prompt：自定义翻译系统提示词。典型用途是给 Qwen 3 附加/no_think指令，例如：--custom-system-prompt "/no_think You are a professional, authentic machine translation engine."
• --add-formula-placehold-hint：为翻译添加公式占位符提示（当前不推荐，可能影响翻译质量，默认False）。
• --disable-same-text-fallback：当 LLM 输出与输入文本相同时，禁用"原样回退"翻译（默认False）。
• --pool-max-workers：内部任务处理池的最大工作线程数；未指定时默认取 QPS 值。该参数直接设置线程数，取代了以前基于 QPS 的动态计算。在TranslationConfig.__init__中可见其默认逻辑：pool_max_workers = pool_max_workers if pool_max_workers is not None else qps。
• --no-auto-extract-glossary：禁用自动术语提取（默认启用，配置文件中对应auto_extract_glossary = false）。

官方提示：

1. 目前仅支持 OpenAI 兼容的 LLM，更多翻译器请使用 PDFMathTranslate 2.0；
2. 推荐使用与 OpenAI 兼容性强的模型，如glm-4-flash、deepseek-chat等；
3. 尚未针对 Bing/Google 等传统翻译引擎优化，建议使用 LLM；
4. 可通过 litellm 接入多种模型；
5. --custom-system-prompt主要用于在提示词中加入 Qwen 3 的/no_think指令。

翻译管线中的 LLM 判定

从 high_level.py 的_do_translate_single可以看到，翻译器若实现了do_llm_translate方法，则使用ILTranslatorLLMOnly；否则回退到传统ILTranslator。自动术语提取阶段AutomaticTermExtractor使用独立的term_extraction_translator（默认与翻译器相同，可通过--openai-term-extraction-*系列参数单独指定模型/地址/密钥），其 token 用量会在结束日志中单独统计。

OpenAI 特定选项

此外 main.py 还支持--openai-term-extraction-model/--openai-term-extraction-base-url/--openai-term-extraction-api-key（为术语提取单独指定模型，未设置时回退到普通翻译参数）、--send-dashscope-header（发送 DashScope 数据检查头以关闭输入/输出检查）、--no-send-temperature（不发送 temperature 参数）、--openai-reasoning（在请求体 reasoning 字段中附加内容）。

官方提示：

1. 本工具支持任何 OpenAI 兼容的 API 端点，只需设置正确的 base URL 与 API key（例如自建服务https://xxx.custom.xxx/v1）；
2. 对于 Ollama 等本地模型，API key 可以填任意值（如--openai-api-key a）。

术语表选项（Glossary）

--glossary-files：逗号分隔的术语表 CSV 文件路径列表。规则如下：

• 每个 CSV 文件需包含source、target列，以及可选的tgt_lng列；
• source列存放原文术语，target列存放目标语言译文；
• tgt_lng（可选）指定该条目适用的目标语言（如"zh-CN"、"en-US"）：
  • 若某条目提供了tgt_lng，则仅当其（归一化后）与--lang-out指定的整体目标语言（归一化后）一致时才会被加载使用；归一化规则为转小写并把连字符-替换为下划线_；
  • 若条目省略tgt_lng，则该条目对任意--lang-out均适用；
• 每个术语表的名称由其文件名（不含.csv后缀）决定，该名称会出现在 LLM 提示词中；
• 翻译时系统会把输入文本与已加载术语表进行比对，若在当前文本段中命中某术语表的词条，就把该术语表（连同相关词条）注入给语言模型的提示词，并附带"必须遵守"的指令。

仓库提供了示例文件 docs/example/demo_glossary.csv，内容如下（注意"a,a"等含逗号、引号的转义写法）：

source,target,tgt_lng AutoML,自动ML,zh-CN "a,a",a,zh-CN """","""",zh-CN

底层实现在 babeldoc/glossary.py：Glossary.from_csv会用 chardet 自动探测文件编码，按tgt_lng过滤条目；加载时对重复的归一化source去重，并基于 hyperscan 编译正则数据库（每 20000 条一个分片，大小写不敏感）实现高速文本命中检测（get_active_entries_for_text）。--lang-out为zh时，示例中的zh-CN条目经归一化（zh-cn）后会被视为匹配而加载。另外，自动术语提取会通过SharedContextCrossSplitPart（见 translation_config.py）跨分拆部分共享、按多数投票去重（Counter.most_common）生成auto_extracted_glossary。

输出控制

• --output,-o：译文输出目录；不设置则使用当前工作目录。从 main.py 看，目录不存在时会自动创建。
• --debug：开启调试日志级别，并把详细的中间结果导出到~/.cache/babeldoc/working（缓存根目录定义在 babeldoc/const.py 的CACHE_FOLDER）。调试模式下_do_translate_single会写出input.decompressed.pdf、create_il.debug.json、layout_generator.json、paragraph_finder.json、il_translated.json、typsetting.json等中间产物，便于逐阶段排查。
• --report-interval：进度上报间隔（秒，默认0.1）。CLI 进度条由 main.py 的create_progress_handler渲染（rich 或 tqdm），事件流由async_translate通过ProgressMonitor产生。

通用选项

• --warmup：仅下载并校验所需资产后即退出（默认False）。适合在正式翻译前预取模型与字体，或在 CI 中验证环境就绪。

离线资产管理

• --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 哈希校验完整性（对应 assets.py 的verify_file）；
8. 若要在完全隔离（air-gapped）环境部署，请先在可联网的机器上生成资产包。

配置文件（TOML）

--config,-c：配置文件路径，使用TOML格式，由configargparse.TomlConfigParser(["babeldoc"])解析（见 main.py），键对应 CLI 参数（下划线_与连字符-均可）。完整示例：

[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. only_include_translated_page = false # Only include translated pages in the output PDF. Effective only when `pages` is used. # no-watermark = false # DEPRECATED: Use watermark-output-mode instead 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) # Translation service 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 Options (Optional) # glossary-files = "/path/to/glossary1.csv,/path/to/glossary2.csv" # 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

官方推荐在 Python 中通过 pdf2zh next 的high_level.do_translate_async_stream函数调用 BabelDOC（该函数会异步产出进度事件，可驱动进度条与取消逻辑）。

警告：BabelDOC 的所有 API 都应视为内部 API，任何直接使用 BabelDOC 的行为均不受官方支持。若要在自有服务中集成，建议使用上述 pdf2zh next 入口；当前仓库的 babeldoc/format/pdf/high_level.py 提供的translate（同步）与async_translate（异步事件流）实现可作参考。

架构与设计背景：解析/渲染两阶段管线

README 将 PDF 解析/翻译问题划分为两个主要阶段：

• Parsing（解析）：获取 PDF 的结构，如文本块、图片、表格等；
• Rendering（渲染）：把结构渲染成新的 PDF 或其他格式。

业界一些服务（如 mathpix、Doc2X、MinerU、PDFMathTranslate）会先把 PDF 解析成 XML 之类的结构，再用单一栏阅读顺序（类似 layoutreader）重排渲染，代价是原始版式信息丢失；也有人用 Adobe PDF 解析器生成保留原结构的 Word 文档，但成本较高，且 PDF/Word 在移动端阅读体验不佳。BabelDOC 的差异化方案是：

• 提供一个中间表示（Intermediate Representation，IL），承载解析器的输出结果，并可从该表示渲染出新的 PDF 或其他格式；
• 整个管线是插件化系统，任何人都可以接入新的模型、OCR、渲染器等。

从源码看，该中间表示即 babeldoc/format/pdf/document_il/ 下的 IL 模型（il_version_1.py及配套的 XSD/RNC/RNG Schema），翻译管线在 high_level.py 的TRANSLATE_STAGES中定义，包括：

1. 解析 PDF 并创建中间表示（权重 14.12）
2. 扫描文件检测DetectScannedFile（2.45）
3. 布局解析LayoutParser（14.03）
4. 表格解析TableParser（1.0，仅启用表格翻译时）
5. 段落查找ParagraphFinder（6.26）
6. 公式与样式解析StylesAndFormulas（1.66）
7. 自动术语提取AutomaticTermExtractor（30.0，默认启用）
8. 段落翻译ILTranslator/ILTranslatorLLMOnly（46.96）
9. 排版Typesetting（4.71）
10. 字体映射FontMapper（0.61）
11. 生成绘制指令PDFCreater（1.96）
12. 字体子集化SUBSET_FONT（0.92）
13. 保存 PDFSAVE_PDF（6.34）

各阶段实现位于 document_il/midend/，渲染由 document_il/backend/pdf_creater.py 完成。翻译结束后还会执行 CMAP 重建（fix_cmap）、元数据标记（add_metadata，会在 producer 中写入 "Translation_generated_by_AI,please_carefully_discern" 以便识别、并拒绝二次翻译已翻译文件）以及目录迁移（migrate_toc，交替页模式除外）。

路线图与 1.0 质量目标

官方 Roadmap：

• 添加线条支持
• 添加表格支持
• 添加跨页/跨栏段落支持
• 更高级的排版功能
• 大纲（Outline）支持
• 其他……

1.0 版本的首要目标，是完成从《PDF Reference, Version 1.7》到简体中文、繁体中文、日语、西班牙语四个语言版本的翻译，并满足两项硬性指标：布局错误率低于 1%、内容丢失率低于 1%。

版本号说明

项目采用 Semantic Versioning（语义化版本）+ Pride Versioning 的组合，版本号格式为"0.MAJOR.MINOR"：

• MAJOR：发生 API 不兼容变更，或实现了值得骄傲（proud）的改进时 +1；
• MINOR：发生任何 API 兼容变更时 +1。

其中"API 兼容性"主要指与 pdf2zh next 的兼容性。当前仓库版本为 0.6.2（见 pyproject.toml 与 babeldoc/main.py 的__version__）。

已知问题

官方 README 列出的已知问题：

1. 作者与参考文献部分的解析错误——翻译后会被合并为一个段落；
2. 不支持线条（lines）；
3. 不支持首字下沉（drop caps）；
4. 过大的页面会被跳过。

重要交互说明：--auto-enable-ocr-workaround

官方文档专门强调，当--auto-enable-ocr-workaround为true（命令行或配置文件均可）时，存在如下两阶段交互逻辑（与 translation_config.py 及 high_level.py 的DetectScannedFile阶段对应）：

1. 初始化阶段：TranslationConfig会把ocr_workaround和skip_scanned_detection强制置为false——即使你同时传了--ocr-workaround或--skip-scanned-detection也会被覆盖；
2. 扫描检测阶段（DetectScannedFile）：
   • 若文档被识别为重度扫描件（例如超过 80% 的页面为扫描页）且auto_enable_ocr_workaround为true，系统会尝试把ocr_workaround与skip_scanned_detection都设为true；
   • 若文档未被识别为重度扫描件，则初始化阶段强制写入的false值会保持生效（除非被其他逻辑改变）。

简言之，--auto-enable-ocr-workaround把"是否启用 OCR 处理"的决定权交给系统：它会根据检测结果覆盖手动设置的--ocr-workaround与--skip-scanned-detection。从源码看，该决策结果通过SharedContextCrossSplitPart.auto_enabled_ocr_workaround跨分拆部分共享，并在每个部分翻译前统一应用。

如何贡献

BabelDOC 目前采用"维护者主导"（maintainer-led）的开发模式：欢迎提交 bug 报告、可复现的 PDF、文档修正和小型兼容性修复；涉及解析、渲染、翻译或服务集成行为的改动，请先开 issue 讨论再提交 PR。参与社区互动需遵守 docs/CODE_OF_CONDUCT.md，活跃贡献者可获得 Immersive Translation 月度 Pro 会员兑换码（详见 docs/CONTRIBUTOR_REWARD.md）。

在致谢列表中，项目明确感谢了 PDFMathTranslate、DocLayout-YOLO、pdfminer、PyMuPDF、Asynchronize、PriorityThreadPoolExecutor 等上游项目——这些依赖在 pyproject.toml 中均有对应（例如 PDF 解析使用自带的 pdfminer 运行时与 PyMuPDF，布局检测基于 DocLayout-YOLO 导出的 ONNX 模型，异步编排使用babeldoc/asynchronize/）。仓库内还提供了 docs/ImplementationDetails 系列实现细节文档（PDF 解析、IL 翻译、段落查找、排版、样式与公式等），以及 docs/intro-to-pdf-object.md 这类 PDF 对象入门读物，适合想深入理解翻译管线内部原理的读者继续阅读。

BabelDOC 仍处于早期开发阶段，部分环节还不够完善，但"保留原版式的 LLM 论文翻译"这一路径已经可以通过babeldoc命令行开箱即用：安装、配置好 OpenAI 兼容端点，一行命令即可得到单语与双语对照 PDF。

【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC