Pdf visual translate zh

PDF Visual Translate · 英文 PDF 版式保真中文翻译 Skill

English version

这个 Skill 做什么

这个 Skill 把英文 PDF 转换成视觉上接近原文档的中文 PDF。

它以源 PDF 作为视觉底层，在原坐标覆盖可见英文，再把简洁中文绘制回去。适合可提取文本的 PDF，例如报告、研报、披露文件、白皮书、合同和类幻灯片 PDF。

这个工作流优先保证版式保真，而不是生成可搜索的中文文本层。覆盖模式可能保留底层英文文本；如果用户需要复制、搜索或二次编辑中文，要提前说明。

操作原则

• 翻译前先诊断 PDF。
• 把翻译状态保存在文件中，不依赖聊天上下文。
• 分小批导出、翻译、合并补丁到缓存。
• 除非上下文明确要求翻译，否则保留专有名词、股票代码、产品名、数据集名、URL、邮箱、数字和短代码。
• 交付前做视觉 QA，尤其检查密集表格、图表、彩色表头和法律/披露页。
• 不要把整份 PDF 栅格化，除非用户接受不可搜索的图片型 PDF。

决策指南

适合使用本路线的情况：

• PDF 有可提取的英文文本。
• 用户想要看起来像原文件的中文 PDF。
• 页数、页面尺寸、图表、表格、颜色、Logo、页眉页脚必须稳定。

需要暂停或换路线的情况：

• diagnose_pdf.py 显示文本密度很低：先 OCR，再重试。
• PDF 加密：向用户索要密码或解密后的源文件。
• PDF 含表单字段或注释：页面覆盖翻译可能不会更新字段值或注释内容，需要单独检查。
• 用户需要可选择、可搜索的中文文本：单纯覆盖模式不是理想最终格式，除非额外做干净文本层重建。

快速流程

设置路径：

PDF="/path/to/source.pdf"
WORK="/tmp/pdf-visual-translate-zh"
GLOSSARY="$WORK/glossary.json"
CACHE="$WORK/translations.json"
OUT="$WORK/output-zh.pdf"
mkdir -p "$WORK"
cp references/glossary-template.json "$GLOSSARY"

1. 诊断

运行预检：

python3 scripts/diagnose_pdf.py \
  --source "$PDF" \
  --json-output "$WORK/diagnosis.json"

再检查翻译抽取器看到的元数据：

python3 scripts/visual_translate_pdf.py --inspect --source "$PDF"

如果文档像扫描件或图片型 PDF，先 OCR。文本抽取不可用时，不要继续视觉翻译。

2. 建术语表

先导出一个小批次：

python3 scripts/visual_translate_pdf.py \
  --source "$PDF" \
  --glossary "$GLOSSARY" \
  --cache "$CACHE" \
  --export-batch "$WORK/batch-000.json" \
  --batch-index 0 \
  --batch-size 40 \
  --context-chars 1200

只读这个紧凑批次，识别名称、品牌、股票代码、产品名、数据来源、缩写、表头和重复术语。大量翻译前先更新 GLOSSARY。

3. 预览文本框

在代表性页面渲染候选文本框：

python3 scripts/render_text_box_preview.py \
  --source "$PDF" \
  --glossary "$GLOSSARY" \
  --cache "$CACHE" \
  --pages 1,4,6,12 \
  --output-dir "$WORK/box-preview"

用它提前发现抽取失败、旋转页、文本碎片化和过小表格单元格，避免翻译完才发现无法放回版面。

4. 分批翻译

导出下一批未翻译内容：

python3 scripts/visual_translate_pdf.py \
  --source "$PDF" \
  --glossary "$GLOSSARY" \
  --cache "$CACHE" \
  --export-batch "$WORK/batch-001.json" \
  --batch-index 0 \
  --batch-size 60 \
  --context-chars 1000

只翻译批次中的 items，写成 patch JSON：

{
  "Exact English source string": "简洁、准确、能放回原坐标的中文"
}

合并补丁：

python3 scripts/visual_translate_pdf.py \
  --source "$PDF" \
  --cache "$CACHE" \
  --merge-patch "$WORK/batch-001.patch.json"

重复使用 --batch-index 0。脚本会跳过已有翻译，所以索引 0 表示“下一批未翻译内容”。导出结果包含 0 items 时停止。

5. 重建

python3 scripts/visual_translate_pdf.py \
  --source "$PDF" \
  --output "$OUT" \
  --cache "$CACHE" \
  --glossary "$GLOSSARY" \
  --render-dir "$WORK/qa" \
  --compare-pages 1,4,6,12,16,22,29,37

如果重建生成 .missing.txt，不要把整个文件读进聊天。继续导出紧凑批次、翻译、合并，再重建。

6. 验证

交付前检查渲染出的对照 PNG：

• 页数和页面尺寸与源 PDF 一致。
• 彩色区域上没有突兀白块。
• 没有明显英文段落残留，除非是有意保留。
• 品牌、产品名、股票代码、评级和数据来源没有被误译。
• 密集表格中的中文没有小到不可读。
• 页眉、页脚、页码、颜色、图表和表格几何结构保持稳定。

翻译约束

• 按页面和章节上下文翻译，不要孤立处理碎片。
• 表格单元格、图例、坐标轴、标题、脚注和页脚要用短中文。
• 除非文档明确采用中文译名，否则保留专有名词和标识符。
• JSON key 必须与英文源字符串完全一致。
• 文档特定规则写进 GLOSSARY，不要把一次性替换硬编码进脚本。
• 对短而含糊的大写词，宁可保留英文，也不要编造中文名。

批次大小建议

• 标签、表格、图表、数字密集页：60-80 项。
• 普通报告正文：30-50 项。
• 法律披露、风险章节、长脚注、密集叙述页：20-30 项。

如果输出过长，立即降低 --batch-size，继续从文件状态推进。

脚本索引

• scripts/diagnose_pdf.py：PDF 预检诊断和路线建议。
• scripts/render_text_box_preview.py：渲染候选文本框，用于视觉验证。
• scripts/visual_translate_pdf.py --inspect：输出面向翻译的元数据。
• scripts/visual_translate_pdf.py --export-batch：导出紧凑、文件化的翻译批次。
• scripts/visual_translate_pdf.py --merge-patch：把一个 patch JSON 合并到缓存。
• scripts/visual_translate_pdf.py --output：重建中文覆盖 PDF。
• REFERENCE.md：OCR、修复、抽取兜底、表单、注释和 QA 的高级路线。
• references/glossary-template.json：每个文档的术语表和 QA 扫描起点。
• references/pdf-translation-qa.md：失败模式、恢复方式和人工检查清单。

大文档硬规则

• 不要把完整 PDF 文本、完整缓存 JSON、完整 translation_jobs.json、完整 .missing.txt 或完整诊断 JSON 粘进聊天。
• 使用 --export-batch 做翻译工作。
• 控制每批大小，让模型能干净翻译。
• 写 patch JSON 文件，然后合并进缓存。
• 把 CACHE、GLOSSARY 和批次文件当作持久状态。
• 如果响应接近输出限制，停止当前批次，降低 --batch-size 后继续。

恢复策略

• 扫描件：先 OCR，再重新诊断和导出批次。
• 缺失翻译：导出下一批紧凑批次，不要读取完整 .missing.txt。
• 术语错误：更新 GLOSSARY，覆盖受影响缓存项，然后重建。
• 中文过小：手动缩短对应缓存译文。
• 表格或产品名被误译：添加精确术语或 keep_as_source。
• 搜索/复制仍是英文：说明覆盖模式限制，或改走干净文本层重建方案。