pdf-translate

PDF 翻译

使用随附的 Code4Life 引擎翻译 PDF。保持源文件不变，并生成单独的 PDF，同时保留相同的页面结构。

在仓库中运行此技能时，请先阅读 agent-knowledge/index.md。如需保留或调整版式，请加载其中的 PDF 引擎、回归测试和验证路线。这些是 Codex 和 Claude 共用的项目说明；请勿在此入口文件中重复。

确定技能根目录

此技能可能全局安装，而用户的文件位于其他位置。运行任何操作前，请确定包含此 SKILL.md 的绝对目录。请使用绝对路径调用其脚本和依赖文件；不要假设当前工作目录就是技能目录。

使用 <skill-root>/.venv 中的解释器：

• Windows：<skill-root>\.venv\Scripts\python.exe
• macOS/Linux：<skill-root>/.venv/bin/python

选择模式

模式	翻译器	适用场景
Google（默认）	translate.google.com	书籍、批量文档、初稿或低 token 用量
交接	当前 Agent	术语、上下文或翻译质量很重要

默认使用 Google。用户要求更高质量、拒绝 Google 的结果或提供简短技术文档时，提供交接选项。

限制

• 使用随附的 pdf2zh/ 核心。切勿替换为 PyPI 上的 pdf2zh 包；运行器会检查版本 1.9.11 和保留规则集 code4life-preservation-v1，并拒绝使用外部核心。
• Google 模式会将提取的文档文本发送到 Google。处理敏感材料前，请告知用户并征得明确确认，除非其请求已授权披露。交接模式不会联系 Google。
• 支持的目标语言仅限 scripts/translate_pdf.py 强制规定的拉丁字母代码。由于随附字体和版式引擎无法可靠渲染，系统会拒绝中文、日文、韩文、从右向左书写的语言、泰语、天城文及其他复杂字形塑形语言。
• OCR 需通过 --ocr standard|enhanced 显式启用。遇到不安全的表格、公式、图表、代码或阅读顺序不明确的内容时，操作会安全失败；请将每个保留区域报告为部分翻译，不要声称整份扫描件均已翻译。
• 检测到的表格、图表、目录页、索引、符号列表或参考文献中的文本可能会有意保留源语言。对于未翻译的重要区域，请报告为部分翻译。
• 保留源文件。将结果写入单独的输出目录。未经明确授权替换文件，切勿传入 --overwrite。

更改版式行为、诊断保留的页面或调查未翻译区域前，请阅读保留规则。

设置运行环境

使用 Python 3.11 或 3.12。如果环境缺失或已过时，请创建 <skill-root>/.venv 并安装 <skill-root>/requirements.txt。此环境应与用户的项目环境分开。

源代码发行包会在首次翻译时下载版式和字体资源，因此首次运行需要网络连接，耗时也会更长。打包的 Windows 应用已包含这些资源。

Windows：

python -m venv "<skill-root>\.venv"
& "<skill-root>\.venv\Scripts\python.exe" -m pip install -r "<skill-root>\requirements.txt"

macOS/Linux：

python3 -m venv "<skill-root>/.venv"
"<skill-root>/.venv/bin/python" -m pip install -r "<skill-root>/requirements.txt"

运行器的通用选项包括 --target-language（默认 vi）、--source-language auto、从 1 开始计数的 --pages 1,3-5、--threads 1..8（默认 4；Google 模式仍会一次发送一个请求）、--ignore-cache 和 --overwrite。--bilingual side-by-side|alternating|layers（默认 off）还会根据源文件和完成的译文生成 <name>-<lang>-dual.pdf；它不会更改译文文件。如果无法生成该文件，运行器会打印警告并保留译文。

Google 模式

每个文件运行一条命令。输入路径和输出目录请使用绝对路径。

Windows：

& "<skill-root>\.venv\Scripts\python.exe" "<skill-root>\scripts\translate_pdf.py" "<input.pdf>" --output-dir "<output-dir>"

macOS/Linux：

"<skill-root>/.venv/bin/python" "<skill-root>/scripts/translate_pdf.py" "<input.pdf>" --output-dir "<output-dir>"

批量处理时，逐个处理文件并报告进度。单个文件发生故障不得中止其余文件。Google 拦截或服务中断耗尽重试次数时，暂停整个队列；成功翻译的内容会缓存，以便稍后重试；被中断的文件不会发布未完成的 PDF。

Google 模式会在一个请求中发送页面的所有片段，并且一次只发送一个请求，因为免费端点会拦截请求过多的网络。切勿并行运行多个 Google 任务。

如果运行时遇到 HTTP 429 或 CAPTCHA，运行器会停止处理当前文档并暂停队列。在接下来的 10 分钟内，它会在执行 OCR/模型处理前拒绝进一步的 Google 运行。这是应用的冷却时间，并不代表 Google 恢复服务所需的时间。不要循环重试，也不要试图绕过 CAPTCHA。请报告此情况，然后提供稍后重试（已完成的片段会缓存）或切换到交接模式的选项。

交接模式

交接模式会将待翻译片段提取到 JSONL 文件，交由当前 Agent 翻译，然后重建 PDF。处理大型文档前，请提醒用户注意令牌消耗和时间成本。对于长文档，建议先抽取有代表性的样本，例如 --pages 1-5。

1. 提取

提取时不需要输出目录，因为第一遍生成的 PDF 会被丢弃。

<python> <skill-root>/scripts/translate_pdf.py <input.pdf> --engine handoff --emit-segments <segments.jsonl>

2. 翻译

分批读取 segments.jsonl，每批控制在适当大小。每行向 translations.jsonl 写入一个 JSON 对象：

{"src":"exact source text","dst":"translated text"}

逐字复制每个 src 值。保留 URL、路径、标识符、引用标记和数字。

公式和代码占位符（如 <b0></b0>）不可更改。每个开始和结束标签都必须与源内容中的标识符、数量和顺序完全一致。如果记录中的占位符不匹配，加载器会拒绝该记录，并保留该片段的未翻译状态。

行内强调标记必须作为成对标记保留：<s1>...</s1> 表示粗体，<s2>...</s2> 表示斜体，<s3>...</s3> 表示粗斜体。完整的样式标记对可以随翻译后的短语移动，但不得删除、重复或交叉嵌套。样式标记无效时，该片段会保持未翻译状态，而不会静默丢失强调样式。

3. 重建

<python> <skill-root>/scripts/translate_pdf.py <input.pdf> --engine handoff --segments <translations.jsonl> --output-dir <output-dir> --emit-segments <still-missing.jsonl>

该命令会显示剩余未翻译片段的数量。如果数量不为零，请翻译 still-missing.jsonl，将有效记录追加到 translations.jsonl，然后再次重建。只有剩余数量为零，或某个片段无法安全翻译时，才停止；随后报告确切的剩余限制。

提取和重建都会各自运行一次版面处理，因此除了 Agent 的翻译工作外，交接模式的本地 PDF 处理量约为 Google 模式的两倍。

交付前验证

1. 确认输出文件存在，且源文件仍存在并未更改。
2. 确认源文件和输出文件的页数一致。
3. 逐页提取文本，并检查是否存在大段内容未翻译、公式缺失、URL 损坏或标识符丢失。
4. 如果支持页面渲染或图像检查，请渲染每一页输出内容，并检查是否存在空白页、字形缺失、裁切、重叠，以及表格或图形移位。
5. 如果无法进行完整的视觉检查，请说明已完成哪些检查。不得将仅部分验证或部分翻译的文件说成已完整处理。