translate-paper-pdf-to-md

KO | EN

gitlite — search

#java #javascript #php #rust #docker #python #hacktoberfest #c-plus-plus #css #sqlite #es6 #react

translate-paper-pdf-to-md

★ 36 Open GitHub ↗

Translate English academic PDF papers into polished target-language Markdown documents while preserving figures, tables, equations, citations, and document structure. Use when Codex is asked to turn an English research PDF into a localized .md paper with extracted visual assets and editable reconstructed content.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Translate Paper PDF to MD

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

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

English README: [README.en.md](README.en.md)

## 它能做什么

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

## 仓库结构

```text
.
├── 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 目录：

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

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

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

## 在 Codex 中使用

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

示例 prompt：

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

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

## 辅助脚本

准备 PDF 抽取工作目录：

```bash
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 批量裁剪图表：

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

然后运行：

```bash
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：

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

示例输出：

```text
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 内嵌图片和表格
- 公式、引用和参考文献

输出：

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

translate-paper-pdf-to-md

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README