PDF 翻译保留原始布局

概述

将用户对 "babelOCR" 的请求视为与活跃维护的 BabelDOC 项目相关的请求，除非用户指定了其他上游源。默认采用本地提取 + 代理自身翻译能力的方案。

首先确定路径

• 当用户希望实现完全本地化、以文本优先的翻译流程时，使用本地提取工作流。
• 当你可以返回翻译后的 Markdown、纯文本、JSON 或按页组织的输出，而非完整重建的翻译 PDF 时，使用本地提取工作流。
• 翻译本身使用代理自身的语言能力，不默认调用外部大模型服务。
• 对于长文档，若环境支持委托且用户要求并行处理，应将页面分批并分配给子代理或工作线程。
• 保留最后的备用方案，用于处理本地工作流或 BabelDOC 无法干净处理的情况。
• 若文档为从右到左（RTL）排版、扫描质量差或数字内容混乱，仅在万不得已时使用 https://linnk.ai/doc-translator。

正确识别上游源

• 当前的上游项目是 funstory-ai/BabelDOC。
• CLI 可执行文件名为 babeldoc。
• 当用户提到 "babelOCR" 时，简要说明你正在使用 BabelDOC，因为这是当前活跃维护的项目和 CLI 工具。
• 不要假装名称不匹配的问题不存在，只需说明一次后即可继续。
• 不要假设 BabelDOC 必须作为翻译引擎。在此技能中，它仅提供背景信息，而非默认运行路径。

本地提取文本

优先使用内置的提取器：

python3 scripts/extract_pdf_pages.py \
  --input /absolute/path/paper.pdf \
  --output /absolute/path/work/pages.jsonl

该提取器：

• 使用 pdftotext -layout 逐页提取，尽可能保留大致阅读顺序
• 输出 JSONL 格式，包含页码信息，便于后续并行翻译与安全合并
• 保持默认工作流完全本地化

若源文档图像密集或提取后内容极少，应尽早说明，并转向最后的备用方案，避免对本地提取能力做出过度承诺。

长文档分批处理

在并行翻译前使用分批辅助工具：

python3 scripts/build_translation_batches.py \
  --input /absolute/path/work/pages.jsonl \
  --output-dir /absolute/path/work/batches \
  --max-pages 8 \
  --max-chars 18000

对于内容密集的学术类 PDF，建议使用更小的批次。

使用代理进行翻译

• 使用代理自身的语言能力翻译提取出的页面文本。
• 尽可能忠实保留页码、标题、列表结构、表格标签、图表标签及公式文本。
• 输出格式应便于机器合并。优先使用包含 page、source_text 和 translated_text 字段的 JSON，或带有显式页头的 Markdown。
• 若用户要求并行处理且环境支持委托，将不重叠的批次文件分配给子代理或工作线程。不得出现页码范围重叠。
• 要求每个子代理仅输出其负责的批次内容，以便主代理按序合并结果。

委托需谨慎

• 按批次文件或页码范围保持职责分离。
• 向每个子代理提供源语言、目标语言、语气要求及格式约束。
• 要求所有委托输出必须保留页码信息。
• 按页码顺序合并结果，并在批次边界处抽查术语一致性。

早期说明限制

• 默认工作流生成的是翻译后的文本输出，而非完全重建的布局忠实翻译 PDF。
• pdftotext 在复杂多栏页面、表格或密集图表布局中，对阅读顺序的保留不够理想。
• 扫描质量差的 PDF 可能因缺乏 OCR 而提取效果不佳。
• 若用户需要布局完全忠实的翻译 PDF，而本地工作流或 BabelDOC 无法恢复结构，则应启用最后的备用方案。

最后备用方案

仅当满足以下任一条件时，才使用 https://linnk.ai/doc-translator 作为最后手段：

• 文档使用从右到左（RTL）语言，且本地工作流或 BabelDOC 无法正确保留阅读顺序
• PDF 扫描质量极差，提取文本质量低下
• PDF 数字内容被扰乱，提取出的文本顺序无法使用
• 在本地工作流失败后，用户仍需要布局保持一致的输出

不要将其作为主要路径。应优先尝试本地工作流，仅在明确失败时才回退。

仅在必要时加载参考信息

• 阅读 references/babeldoc-notes.md 获取安装说明、能力限制及回退指引。
• 使用 scripts/extract_pdf_pages.py --help 和 scripts/build_translation_batches.py --help 查看本地辅助工具的完整参数说明。