translate-pdf

端到端翻译 PDF 文档：从源 PDF 中提取结构化 Markdown，翻译内容，并生成目标语言的新版 PDF。

用法：

• /translate-pdf ./report.pdf French English — 将法语 PDF 翻译成英语
• /translate-pdf /path/to/manual.pdf English Spanish — 将英语 PDF 翻译成西班牙语
• /translate-pdf invoice.pdf German French — 将德语 PDF 翻译成法语

说明：

1. 解析位置参数：

   • $1 = 源 PDF 文件的路径
   • $2 = PDF 当前使用的语言
   • $3 = 要翻译成的语言
   • 如果缺少 $1、$2 或 $3 中的任意一项，请显示以下内容并停止：

     ## 缺少参数
     
     用法：/translate-pdf <path-to-pdf> <source-language> <target-language>
     
     示例：
       /translate-pdf ./report.pdf French English
       /translate-pdf /path/to/manual.pdf English Spanish
       /translate-pdf invoice.pdf German French
     

2. 验证 PDF 文件是否存在：

   • 解析路径并验证文件存在且扩展名为 .pdf
   • 如果文件不存在，请显示错误并停止：

     找不到文件：“<path>”
     请提供有效的 PDF 文件路径。
     

3. 检查 Python 依赖项：

   此技能依赖位于 skills/translate-pdf/translate_pdf.py（相对于此仓库）的 Python 脚本。该脚本需要：

   • pymupdf — 提取 PDF 文本
   • markdown — 将 Markdown 转换为 HTML
   • weasyprint — 将 HTML 渲染为 PDF（还需要系统库：cairo、pango、gdk-pixbuf）

   a) 检查是否已安装依赖项： 通过 Bash 工具运行 python3 -c "import fitz; import markdown; from weasyprint import HTML; print('OK')"。

   b) 如果检查失败，使用 AskUserQuestion 询问开发者：

   以下 Python 包为必需项，但并非全部已安装：

   • pymupdf（提取 PDF）
   • markdown（Markdown → HTML）
   • weasyprint（HTML → PDF，还需要系统库：cairo、pango、gdk-pixbuf）

   是否现在安装这些包？

   提供两个选项：

   • 是 — 使用 pip 安装 → 运行 pip install pymupdf markdown weasyprint
   • 否 — 我会自行处理 → 显示手动安装说明并停止：

     ## 手动安装
     
     安装 Python 包：
       pip install pymupdf markdown weasyprint
     
     weasyprint 还需要系统库。请为你的操作系统安装这些库：
     
     macOS（Homebrew）：
       brew install cairo pango gdk-pixbuf libffi
     
     Ubuntu/Debian：
       sudo apt install libcairo2-dev libpango1.0-dev libgdk-pixbuf2.0-dev libffi-dev
     
     然后重新运行此技能。
     

4. 步骤 1 — 将 PDF 提取为 Markdown：

   确定输出目录 — 使用与源 PDF 相同的目录。

   运行提取脚本：

   python3 <repo-root>/skills/translate-pdf/translate_pdf.py extract "<pdf-path>" -o "<output-dir>/<filename>_source.md"
   

   其中 <filename> 是不含扩展名的 PDF 文件名。

   提取后，读取生成的 Markdown 文件，确认内容看起来合理。如果 Markdown 几乎为空或内容乱码（例如，PDF 是扫描件或基于图像），请提醒开发者：

   此 PDF 似乎是基于图像的，或可提取的文本很少。翻译可能不完整或不准确。建议先使用 OCR 工具。

5. 步骤 1b — 验证表格保留情况：

   提取脚本会使用 PyMuPDF 的 find_tables() 自动检测 PDF 中的表格，并将其转换为 Markdown 表格语法。提取后，必须验证表格是否正确保留：

   a) 使用 Read 工具读取源 PDF，以直观识别文档中的所有表格。记录表格数量及其大致内容（表头、行数）。 b) 阅读提取的 Markdown 文件，并查找所有 Markdown 表格（以 | 开头的行）。对于每个表格，请验证：

   • 表格是否包含表头行、分隔行（| --- | --- |）以及正确数量的数据行
   • 原 PDF 中有数据的单元格是否均有内容且非空
   • 是否保留了多列结构（每行的 | 分隔符数量是否正确）

   c) **比较数量：**如果 Markdown 表格的数量与您在源 PDF 中识别出的表格数量不一致，则可能有些表格未被检测到。对于每个缺失的表格：

   • 确认缺失表格在 PDF 中的页码和位置
   • 阅读提取的 Markdown 中的相关文本，手动重建 Markdown 表格（相关内容可能以纯文本段落的形式出现）
   • 在文件的正确位置插入重建的 Markdown 表格，替换包含表格数据的纯文本段落

   d) **修复格式错误的表格：**如果任何 Markdown 表格存在列数不一致、缺少分隔符或内容乱码的情况，请参考源 PDF 进行修复。确保每一行的列数都相同。

   验证并完成所有修复后，保存更新后的 Markdown 文件。

6. 步骤 2 — 翻译 Markdown：

   阅读提取的 Markdown 文件（<filename>_source.md）。

   按照以下规则，将 <source-language> 中的所有文本内容翻译为 <target-language>：

   • 保留所有 Markdown 格式——标题、粗体、斜体、列表、表格、代码块、链接、图片引用
   • 原样保留所有 Markdown 表格——保持行数、列数、表头行和分隔行不变。翻译单元格内容，但绝不更改表格结构（不得添加、删除或合并列或行）
   • 保留页面注释标记（``）和作为分页符的水平分隔线（---）
   • **不要翻译：**代码片段、URL、文件路径、广为人知的专有名称（品牌名称、产品名称）或技术标识符
   • 自然地翻译——译文应流畅自然，不要逐字翻译
   • 保留文档结构——译文 Markdown 应与源文件包含相同数量的章节、段落、表格和结构元素

   将翻译后的内容写入 <output-dir>/<filename>_<target-language>.md（例如：report_English.md）。

7. 步骤 3 — 构建翻译后的 PDF：

   运行构建脚本：

   python3 <repo-root>/skills/translate-pdf/translate_pdf.py build "<output-dir>/<filename>_<target-language>.md" -o "<output-dir>/<filename>_<target-language>.pdf"
   

   验证 PDF 是否已成功生成。

8. 报告结果：

   显示摘要：

   ## Translation Complete
   
   **Source:** <pdf-path> (<source-language>)
   **Target language:** <target-language>
   
   ### Generated Files
   - Source Markdown: `<filename>_source.md`
   - Translated Markdown: `<filename>_<target-language>.md`
   - Translated PDF: `<filename>_<target-language>.pdf`
   
   All files saved in: `<output-directory>/`
   

9. 处理边缘情况：

   • 如果 PDF 受密码保护，请显示错误并停止
   • 如果 PDF 完全没有可提取的文本，请警告开发者并停止
   • 如果构建步骤因缺少系统库（weasyprint 依赖项）而失败，请显示步骤 3 中针对相应平台的安装说明
   • 如果源语言和目标语言相同，请警告开发者，并在继续操作前请求确认