translate-book

Rainman Translate Book

English | 中文 | 日本語

An agent skill for Codex, Claude Code, and OpenClaw that translates entire books (PDF/DOCX/EPUB) into any language using parallel subagents.

Inspired by claude_translater. The original project uses shell scripts as its entry point, coordinating the Claude CLI with multiple step scripts to perform chunked translation. This project restructures the workflow as an agent skill for Codex, Claude Code, and OpenClaw, using subagents to translate chunks in parallel, with manifest-driven integrity checks, resumable runs, and multi-format output unified into a single pipeline. As the project structure and implementation differ significantly from the original, this is an independent project rather than a fork.

---

How It Works

Input (PDF/DOCX/EPUB)
  │
  ▼
Calibre ebook-convert → HTMLZ → HTML → Markdown
  (or Markdown input, e.g. from MinerU / Marker, skipping Calibre)
  │
  ▼
Split into chunks (chunk0001.md, chunk0002.md, ...)
  │  manifest.json tracks chunk hashes
  ▼
Parallel subagents (8 concurrent by default)
  │  each subagent: read 1 chunk → translate → write output_chunk*.md
  │  batched to respect API rate limits
  ▼
Validate (manifest hash check, 1:1 source↔output match)
  │
  ▼
Merge → Pandoc → HTML (with TOC) → Calibre → DOCX / EPUB / PDF

Each chunk gets its own independent subagent with a fresh context window. This prevents context accumulation and output truncation that happen when translating a full book in a single session.

Features

• Parallel subagents — 8 concurrent translators per batch, each with isolated context
• Resumable + selective re-translation — chunk-level resume, with run_state.json tracking glossary-sensitive re-translation
• Neighbor context — each chunk can see short read-only excerpts from adjacent chunks for pronoun and entity resolution
• Manifest validation — SHA-256 hash tracking prevents stale or corrupt outputs from being merged
• Multi-format output — HTML (with floating TOC), DOCX, EPUB, PDF
• Optional output controls — explicit EPUB cover, custom temp root, and user-facing export aliases
• Multi-language — zh, en, ja, ko, fr, de, es (extensible)
• PDF/DOCX/EPUB/Markdown input — Calibre handles the conversion heavy lifting; formula- and table-heavy PDFs can be pre-extracted to Markdown with MinerU or Marker

Prerequisites

• Agent runtime — Codex, Claude Code, or OpenClaw, installed and ready to run skills
• Calibre — ebook-convert command must be available (download)
• Pandoc — for HTML↔Markdown conversion (download)
• Python 3 with:
  • pypandoc — required (pip install pypandoc)
  • beautifulsoup4 — optional, for better TOC generation (pip install beautifulsoup4)
• MinerU or Marker — optional, only to pre-extract formula- and table-heavy PDFs to Markdown (see Step 1)

Quick Start

1. Install the skill

Codex

npx skills add deusyu/translate-book -a codex -g

Or install it manually:

mkdir -p ~/.agents/skills
git clone https://github.com/deusyu/translate-book.git ~/.agents/skills/translate-book

Restart Codex if the newly installed skill does not appear.

Claude Code

npx skills add deusyu/translate-book -a claude-code -g

Or install it manually:

mkdir -p ~/.claude/skills
git clone https://github.com/deusyu/translate-book.git ~/.claude/skills/translate-book

OpenClaw

openclaw skills install @deusyu/translate-book

2. Translate a book

Codex

In the Codex CLI or IDE extension, enter:

$translate-book Translate /path/to/book.pdf into Chinese.

Codex can also select the skill automatically when your request matches its description.

Claude Code and OpenClaw

Ask the agent:

translate /path/to/book.pdf to Chinese

In Claude Code, you can also use the slash command:

/translate-book translate /path/to/book.pdf to Japanese

The skill handles the full pipeline automatically — convert, chunk, translate in parallel, validate, merge, and build all output formats.

3. Find your outputs

All files are in {book_name}_temp/:

File	Description
output.md	Merged translated Markdown
book.html	Web version with floating TOC
book.docx	Word document
book.epub	E-book
book.pdf	Print-ready PDF

Repository Test Assets

• Checked-in baseline inputs live under tests/baselines/<book-id>/.
• Generated full-pipeline outputs live under tests/.artifacts/ and should not be committed.
• Because scripts/convert.py writes {book_name}_temp/ under the current working directory, run repository baseline tests from inside tests/.artifacts/ to keep generated files out of the repo root.

Full-Pipeline Baseline Example

mkdir -p tests/.artifacts
cd tests/.artifacts
python3 ../../scripts/convert.py ../baselines/standard-alice/standard-alice.epub --olang zh
# then run translation via the skill
python3 ../../scripts/merge_and_build.py --temp-dir standard-alice_temp --title "test"

Feedback and Contributions

Please open a detailed GitHub issue instead of starting with a pull request. This project is maintained as an AI-assisted skill pipeline, and changes need to be evaluated against the current orchestration rules, chunk/manifest contracts, baseline assets, and release flow in one maintainer-owned context.

Pull requests are not the preferred contribution path and may be closed in favor of an issue. If you already have a patch, include the idea, key diff, failing case, or verification notes in the issue; the maintainer may rework or split the implementation before merging.

A useful issue should include:

• Current behavior and expected behavior
• Input format and environment, such as PDF/DOCX/EPUB, OS, Python, Calibre, and Pandoc versions
• Minimal reproduction steps or a small public-domain sample when possible
• Logs, screenshots, or generated file names that show the failure

Contact

For bugs and feature requests, please open a GitHub issue as described above. For questions, ideas, or anything else, you can reach me here:

Channel	Link
X (Twitter)	@0xdeusyu
Telegram	@DeusThink
Telegram Group (Chinese)	@talkdeusyu
Telegram Channel (Chinese)	@lovedesuyu
Email	rainman.deus@gmail.com

For commercial sponsorship, see Commercial sponsorship below.

The channel is my running log of thinking alongside AI; the group is its discussion space, and translate-book questions are welcome there too.

Pipeline Details

Step 1: Convert

python3 scripts/convert.py /path/to/book.pdf --olang zh

Calibre converts the input to HTMLZ, which is extracted and converted to Markdown, then split into chunks (~6000 chars each). A manifest.json records the SHA-256 hash of each source chunk for later validation, and a source_fingerprint.json ties the temp dir to the exact source bytes it was built from — re-running against a replaced source file aborts instead of silently reusing stale chunks. Temp dirs created before fingerprinting are adopted with a warning on first re-run.

The HTML → Markdown step also cleans Calibre's markup structurally. EPUB footnotes — a marker link such as <a href="#n1"><sup>1</sup></a> in the text, paired with a note paragraph that opens with a link back to it — become Pandoc footnotes ([^1] in the text, [^1]: … right after the paragraph), numbered across the whole book so that per-chapter numbering cannot collide after merging. In-book links keep their text, span attributes such as {lang="…"}, empty page anchors, and heading ids are dropped, and typographic dashes and quotes stay as Unicode instead of --- or escaped ASCII quotes. Notes without a back-link (for example EPUB 3 <aside> footnotes) stay ordinary paragraphs.

By default the working directory is {book_name}_temp/ under the current directory. Use --temp-root /path/to/work to keep the same leaf directory name under a different parent.

Formula- and table-heavy PDFs: convert Markdown instead (optional)

Calibre reflows PDF text by coordinate heuristics. That works for plain prose, but academic and technical PDFs lose their structure: formulas break into fragments, tables flatten into one cell per line, and multi-column pages interleave. For those PDFs, extract them with a layout-aware parser first and give convert.py the Markdown it writes. .md / .markdown input skips Calibre entirely:

pip install -U "mineru>=4.0,<5"                # or: pip install marker-pdf
mineru-kit parse paper.pdf -o paper.md         # MinerU >= 4 (CPU-only basic tier: ~0.8 GB of models)
# marker_single paper.pdf --output_dir out/    # Marker: writes out/paper/paper.md
python3 scripts/convert.py paper.md --olang zh

The parsers keep formulas as $...$ / $$...$$ LaTeX and tables as tables. convert.py copies images referenced next to the Markdown file, and decodes the base64 images MinerU inlines, into {book_name}_temp/images/, so chunks never carry image payloads. Display-math blocks ($$ ... $$) are never split across chunks. YAML front matter (title, author, lang) fills config.txt and is not sent for translation; without it, a leading # heading becomes original_title. The temp dir is named after the Markdown file, so paper.md maps to paper_temp/. If that dir was built from paper.pdf, convert.py aborts on the source-fingerprint mismatch, so delete it first. Both parsers download ML models on first run. --strip-page-numbers and --detect-page-numbers only apply to Calibre input.

At build time Pandoc renders $...$ / $$...$$ as MathML, so formulas are typeset in book.html and book.pdf, and in book.epub on readers that support MathML. Calibre's DOCX output cannot typeset MathML: formulas appear there as flattened text followed by their TeX source.

Step 1.5: Glossary (term consistency across chunks)

Each chunk is translated by a fresh-context sub-agent, which means the same proper noun can drift across multiple translations on a 100-chunk book. To fix this, the skill builds a glossary before translation:

1. Sample 5 chunks (first, last, 3 evenly-spaced middle).
2. Extract proper nouns and recurring domain terms; pick canonical translations.
3. Write <temp_dir>/glossary.json (hand-editable schema below).
4. Run python3 scripts/glossary.py count-frequencies <temp_dir> to populate per-term frequencies (ASCII terms use word-boundary regex so cat doesn't match category; CJK terms use substring; single-CJK-char terms are rejected; aliases count toward the term they belong to).
5. For each chunk, the orchestrator calls python3 scripts/glossary.py print-terms-for-chunk <temp_dir> chunkNNNN.md and injects the resulting 3-column (原文 | 别名 | 译文) markdown table into that chunk's prompt as a hard constraint. Term selection = (terms whose source OR any alias appears in this chunk) ∪ (top-N most-frequent book-wide).