Translate Paper PDF to MD

把英文 PDF 学术文献翻译成高质量的目标语言 Markdown 文档，同时保留论文结构、图片、表格、公式、引用和参考文献。

这个仓库提供一个 Codex skill。它不是“一键 PDF 机翻”的路线，而是更适合读论文、整理文献和二次编辑的工作流：抽取文本和页面图片，先询问论文领域与翻译偏好，再重建可编辑 Markdown；必要时裁剪原论文图表；最后检查图片链接、引用和公式结构是否完整。

English README: README.en.md

它能做什么

• 将英文研究论文 PDF 转成目标语言 Markdown。
• 保留章节层级、图表编号、公式编号、引用、致谢和参考文献。
• 将图片或复杂表格从 PDF 页面中裁剪到 assets 目录。
• 对普通表格尽量重建为 Markdown 表格。
• 将公式重写为 Markdown 友好的 LaTeX。
• 在正式翻译前询问翻译偏好：
• 目标语言或地区
• 论文领域或子领域
• 目标读者和语气风格
• 术语策略
• 图片和表格处理偏好
• 避免把自动翻译 PDF 当作最终成果。

仓库结构

.
├── README.md
├── README.en.md
└── skills/
    └── translate-paper-pdf-to-md/
        ├── SKILL.md
        ├── agents/
        │   └── openai.yaml
        ├── references/
        │   └── quality-checklist.md
        └── scripts/
            ├── extract_pdf_assets.py
            └── validate_markdown_assets.py

真正的 Codex skill 是 skills/translate-paper-pdf-to-md/。README 文件放在 skill 目录外面，因此不会进入 Codex 运行时的 skill 上下文。

安装

将 skill 目录复制或软链接到 Codex skills 目录：

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -r skills/translate-paper-pdf-to-md "${CODEX_HOME:-$HOME/.codex}/skills/"

本地开发时也可以使用软链接：

ln -s "$PWD/skills/translate-paper-pdf-to-md" \
  "${CODEX_HOME:-$HOME/.codex}/skills/translate-paper-pdf-to-md"

在 Codex 中使用

安装 skill 目录后，按名称调用即可。

示例 prompt：

Use $translate-paper-pdf-to-md to translate /path/to/paper.pdf into Chinese Markdown.
这篇论文方向是分布式系统。请使用忠实、正式的学术中文；
关键英文术语首次出现时保留英文；图片内部标签保留原文；
表格和公式尽量重建成可编辑形式。

如果没有提供这些偏好，skill 会要求 Codex 在正式翻译前先询问。

辅助脚本

准备 PDF 抽取工作目录：

skills/translate-paper-pdf-to-md/scripts/extract_pdf_assets.py paper.pdf \
  --work-dir paper_zh_work \
  --assets-dir paper_zh_assets

它会生成：

• source_layout.txt
• source_raw.txt
• page_images/ 下的页面渲染图

也可以用 JSON spec 批量裁剪图表：

{
  "fig1_overview.png": {"page": 2, "crop": "800x360+120+420"},
  "table1_original.png": {"page": 3, "crop": "1000x240+100+160"}
}

然后运行：

skills/translate-paper-pdf-to-md/scripts/extract_pdf_assets.py paper.pdf \
  --work-dir paper_zh_work \
  --assets-dir paper_zh_assets \
  --crop-spec crops.json

检查最终 Markdown：

skills/translate-paper-pdf-to-md/scripts/validate_markdown_assets.py paper_zh.md

示例输出：

image_links: 19
missing_images: 0
reference_entries: 94
figure_numbers_seen: 1, 2, 3, ...
table_numbers_seen: 1, 2, 3, ...
equation_tags_seen: 1, 2, 3, 4

效果示例

输入：

• 英文 PDF 学术论文
• PDF 内嵌图片和表格
• 公式、引用和参考文献

输出：

paper_zh.md
paper_zh_assets/
├── fig1_*.png
├── fig2_*.png
├── table1_original.png
└── ...
paper_zh_work/
├── source_layout.txt
├── source_raw.txt
└── page_images/

生成的 Markdown 文档适合阅读、继续编辑，也方便后续转换成 HTML、PDF 或 DOCX。

Token 成本粗估

非常不严谨地按一次 23 页论文的完整处理流程估算，token 成本大约为 0.7 美元。

这个数字只适合作为数量级参考。实际花费会随模型价格、论文页数、图表密度、文本抽取质量、重试次数、是否额外复核、目标语言和最终输出长度而变化。

依赖

建议安装以下命令行工具：

• pdfinfo
• pdftotext
• pdftocairo
• pdfimages
• ImageMagick 的 convert

仓库里的 Python 脚本只依赖 Python 标准库。

说明

• 该 skill 当前主要面向英文源论文。其他源语言可能也能使用，但默认流程和提示以英文输入为前提。
• 图片内部标签通常保留原文，避免重绘引入错误；图题和正文解释会翻译。
• 参考文献通常保留原文，方便检索；如果用户明确要求，也可以翻译参考文献说明。