📄 Transpaper

English AI papers in. Korean-first, publication-minded PDFs out.

Transpaper rebuilds academic PDFs for natural Korean reading while preserving the visual evidence that should not be rewritten: figures, tables, equations, captions, author metadata, footnotes, appendices, and references.

Quick start · Examples · How it works · Security · Contributing

Important

Transpaper is not an offline translator. It sends extracted paper text and selected page-render images to OpenAI through your local Codex CLI login, or through the optional OpenAI API mode.

✨ What makes it different

	Transpaper behavior
🇰🇷 Korean-first typesetting	Builds a new reading layout instead of squeezing translated strings into the original English text boxes.
🧭 Strict translation boundary	Translates only the title, abstract, body headings, and body paragraphs.
🖼️ Visual preservation	Reuses figures, tables, equations, and their source regions without asking a model to recreate them.
🧪 Fail-closed max quality	Analysis, terminology memory, draft, review, consistency, visual QA, and publication gates must pass.
🔐 Local credential delegation	Uses the installed codex executable; Transpaper does not read or copy your ChatGPT credential.
🧰 Inspectable artifacts	Keeps the parsed document, translation units, review output, snapshots, and render reports for debugging.

Translation scope

Content	Result
Title, abstract, body section headings, body paragraphs	Translated into Korean
Figures, tables, equations	Preserved from the source PDF
Captions, author/affiliation blocks, footnotes	Kept in the original language
Acknowledgments, appendix, references	Kept in the original language

🚀 Quick start

1. Install and sign in to Codex CLI

Follow the current official Codex CLI guide. On macOS or Linux, the official standalone installer is:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

On the first run, choose Sign in with ChatGPT. Then verify the login:

codex login status

2. Clone and install Transpaper

git clone https://github.com/LikeACloud7/transpaper.git
cd transpaper

# Recommended: reproducible environment from uv.lock
uv sync

No uv yet? Install it from the official uv guide, or use an editable virtual environment:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

3. Translate a paper

uv run transpaper paper.pdf

When --model is omitted, Codex CLI selects its available default model. To choose a specific model your account supports:

uv run transpaper paper.pdf --model MODEL_NAME

🎬 Examples

1. Publication-gated translation

uv run transpaper "papers/attention-is-all-you-need.pdf"

papers/
├── attention-is-all-you-need.pdf
├── attention-is-all-you-need.ko.pdf
└── .attention-is-all-you-need.ko.transpaper/
    ├── document_ast.json
    ├── document_profile.json
    ├── translation_units.json
    ├── qa_scorecard.json
    ├── quality_gate.json
    └── snapshots/

max is the default. It may stop without claiming success when the document-specific quality or renderer safety gates fail.

2. Faster draft into a separate folder

uv run transpaper paper.pdf \
  --quality balanced \
  --output ./translated

balanced skips the publication-grade critic loop and is explicitly an unreviewed draft.

3. Enforce project terminology

Create terms.csv:

English,Korean
transformer,트랜스포머
attention mechanism,어텐션 메커니즘
fine-tuning,미세 조정
reinforcement learning,강화 학습

Then run:

uv run transpaper paper.pdf --glossary terms.csv

The bundled glossary/cs_terms.csv is used automatically when no custom glossary is provided.

4. Add document-specific translation guidance

uv run transpaper paper.pdf --prompt my-academic-style.txt

The custom prompt is shared across document analysis, translation, review, and consistency stages. Equations, citations, code, and protected document regions remain outside the translation scope.

5. Use the local web UI

uv run transpaper --web
# Open http://127.0.0.1:7860

The Gradio server binds to localhost and public sharing is disabled by default.

🔌 Optional OpenAI API mode

Codex CLI is the default and requires no API key in Transpaper. API mode is available for users who deliberately want project-based API billing:

cp .env.example .env
# Edit .env and set OPENAI_API_KEY. Never commit this file.

uv run transpaper paper.pdf \
  --auth api \
  --model MODEL_NAME

API mode requires an explicit model name because model access differs across OpenAI projects.

⚙️ How it works

flowchart LR
    A["English paper PDF"] --> B["Structure extraction"]
    B --> C["Document AST"]
    C --> D["Codex analysis + terminology memory"]
    D --> E["Draft translation"]
    E --> F["Review + consistency pass"]
    F --> G["Korean-first PDF renderer"]
    G --> H["Visual QA + publication gate"]
    H -->|pass| I["Korean PDF"]
    H -->|fail closed| J["Artifacts + actionable report"]
    C --> K["Original figures · tables · equations"]
    K --> G

Loading

The parser and renderer use PyMuPDF. Language work runs through non-interactive codex exec calls or the optional OpenAI API client. Codex calls use an ephemeral session, an isolated temporary working directory, ignored local rules, and a read-only sandbox.

🧪 Tested academic layouts

The pinned, checksum-verified regression corpus contains 10 papers across 7 sources:

Source	Coverage
arXiv	General and recent preprint layouts
ICML · ICLR · NeurIPS	ML conference templates, equations, figures, and dense two-column pages
ACL · EMNLP · NAACL	NLP templates, footnotes, run-in headings, tables, and long references

The matrix checks body-only translation boundaries, appendix/reference cutoffs, heading recovery, caption-to-visual links, visual preservation, orphan regions, broken glyphs, and output-page growth.

# Verify already downloaded samples
uv run python scripts/verify_venue_matrix.py

# Fetch missing public samples, verify SHA-256, then test
uv run python scripts/verify_venue_matrix.py --download

# Exercise the real renderer as well
uv run python scripts/verify_venue_matrix.py --download --render-identity \
  --report tmp/venue-matrix/report.json

This is a reproducible compatibility gate, not a promise that every publisher PDF has the same structure.

🧭 Quality modes

Mode	Best for	Behavior
max	Reading, sharing, or close review	Multi-pass translation, consistency and visual review, mandatory quality gate; fails closed.
balanced	Fast iteration	Shorter pipeline; output is an unreviewed draft.

🔒 Privacy & security

• Remote processing: paper text and selected page images are sent to OpenAI. Check your current OpenAI account/workspace data controls before using confidential, personal, export-controlled, or regulated material.
• Local artifacts: .<output-stem>.transpaper/ can contain source text, translations, page images, and model review output. Delete it when no longer needed.
• Credentials: Codex mode delegates authentication to the official CLI. API mode reads OPENAI_API_KEY from the environment or ignored .env file.
• Command isolation: model names and paths are passed as subprocess argument lists, not through a shell. Codex runs in a temporary directory with a read-only sandbox.
• Web UI: localhost-only by default. Do not expose it publicly without adding your own authentication and network controls.
• Untrusted PDFs: keep PyMuPDF and the rest of the lockfile updated before processing files from unknown sources.

See SECURITY.md for the reporting policy and full trust boundary.

🛠️ Troubleshooting

Codex CLI not found

Install Codex using the official guide, restart the terminal, and confirm codex --version works.

Codex CLI login is not ready

Run codex, choose Sign in with ChatGPT, then check codex login status.

The selected model is unavailable

Omit --model to let Codex choose its default, or pass a model available to your account. In API mode, pass a model enabled for that API project.

Max quality stopped without a PDF

Inspect quality_gate.json, qa_scorecard.json, and render_validation.json in the hidden artifact directory. Use balanced only if an unreviewed draft is acceptable.

⚠️ Current limitations

• Designed for born-digital English academic PDFs; scanned papers need OCR before Transpaper.
• Complex or unusual publisher layouts may fail the strict gate instead of producing a misleading result.
• Translation requires network access and sufficient Codex or API usage allowance.
• This repository currently supports source installs from a Git clone; it is not published as a PyPI release.

🧑‍💻 Development

uv sync
uv run python -m unittest discover -s tests -v

Parser or renderer changes should also pass the venue regression matrix. Read CONTRIBUTING.md before opening a pull request.

📁 Repository map

transpaper/
├── assets/fonts/               # Bundled Korean fonts + OFL license
├── config/
│   ├── prompts/                # Shared academic translation prompt
│   └── venue_regression_samples.json
├── glossary/cs_terms.csv       # Default terminology
├── scripts/                    # Auditing, comparison, and matrix tools
├── src/transpaper/
│   ├── cli.py                  # CLI entrypoint
│   ├── parser.py               # PDF → document AST
│   ├── llm.py                  # Codex/API orchestration
│   ├── renderer.py             # Korean-first PDF typesetting
│   └── web.py                  # Local Gradio UI
└── tests/

📜 License

Transpaper source code is available under the MIT License. Bundled Noto CJK font files remain under the SIL Open Font License 1.1; see THIRD_PARTY_NOTICES.md.

---

Built for researchers who want to read the paper, not fight the PDF.