Translate Book Parallel

Translate Book (Parallel Subagents)

Skill by ara.so — Daily 2026 Skills collection.

A Claude Code skill that translates entire books (PDF/DOCX/EPUB) into any language using parallel subagents. Each chunk gets an isolated context window — preventing truncation and context accumulation that plague single-session translation.

Pipeline Overview

Input (PDF/DOCX/EPUB)  │  ▼Calibre ebook-convert → HTMLZ → HTML → Markdown  │  ▼Split into chunks (~6000 chars each)  │  manifest.json tracks SHA-256 hashes  ▼Parallel subagents (8 concurrent by default)  │  each: read chunk → translate → write output_chunk*.md  ▼Validate (manifest hash check, 1:1 source↔output match)  │  ▼Merge → Pandoc → HTML (with TOC) → Calibre → DOCX / EPUB / PDF

Prerequisites

# 1. Calibre (provides ebook-convert)# macOSbrew install --cask calibre# Linuxsudo apt-get install calibre# Or download from https://calibre-ebook.com/
# 2. Pandocbrew install pandoc        # macOSsudo apt-get install pandoc # Linux
# 3. Python dependenciespip install pypandoc beautifulsoup4

Verify all tools are available:

ebook-convert --versionpandoc --versionpython3 -c "import pypandoc; print('pypandoc ok')"

Installation

Option A: npx (recommended)

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

Option B: ClawHub

clawhub install translate-book

Option C: Git clone

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

Usage in Claude Code

Once the skill is installed, use natural language inside Claude Code:

translate /path/to/book.pdf to Chinese

translate ~/Downloads/mybook.epub to Japanese

/translate-book translate /path/to/book.docx to French

The skill orchestrates the full pipeline automatically.

Supported Languages

Language codes are extensible — add new ones in the skill definition.

Running Pipeline Steps Manually

Step 1: Convert to Markdown Chunks

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

This produces inside {book_name}_temp/:

• chunk0001.md, chunk0002.md, ... (source chunks, ~6000 chars each)
• manifest.json (SHA-256 hashes for validation)

# For EPUB inputpython3 scripts/convert.py /path/to/book.epub --olang ja
# For DOCX inputpython3 scripts/convert.py /path/to/book.docx --olang fr

Step 2: Translate (Parallel Subagents)

The skill handles this step — it launches 8 concurrent subagents per batch, each translating one chunk independently:

# Each subagent receives exactly this task:Read chunk0042.md → translate to target language → write output_chunk0042.md

Resumable: Already-translated chunks (valid output_chunk*.md files) are skipped on re-run.

Step 3: Merge and Build All Formats

python3 scripts/merge_and_build.py \  --temp-dir book_name_temp \  --title "《Book Title in Target Language》"

Before merging, validation checks:

• Every source chunk has a matching output file (1:1)
• Source chunk hashes match manifest.json (no stale outputs)
• No output files are empty

Outputs produced:

Project Structure

translate-book/├── SKILL.md                    # Claude Code skill definition (orchestrator)├── scripts/│   ├── convert.py              # PDF/DOCX/EPUB → Markdown chunks via Calibre HTMLZ│   ├── manifest.py             # SHA-256 chunk tracking and merge validation│   ├── merge_and_build.py      # Merge chunks → HTML → DOCX/EPUB/PDF│   ├── calibre_html_publish.py # Calibre wrapper for format conversion│   ├── template.html           # Web HTML template with floating TOC│   └── template_ebook.html     # Ebook HTML template└── README.md

How Manifest Validation Works

# scripts/manifest.py (conceptual usage)
# During convert.py — records source hashesmanifest = {    "chunk0001.md": "sha256:abc123...",    "chunk0002.md": "sha256:def456...",    # ...}
# During merge_and_build.py — validates before merging# 1. Check every chunk has a corresponding output_chunk# 2. Re-hash source chunks and compare against manifest# 3. Reject if any hash mismatches (stale/corrupt output)# 4. Reject if any output file is empty

If validation fails, the script auto-deletes stale output.md and re-merges from valid chunk outputs.

Real-World Example: Translate a Technical Book

# 1. Install the skillnpx skills add deusyu/translate-book -a claude-code -g
# 2. Open Claude Code in your working directorycd ~/books
# 3. Say in Claude Code:# "translate clean-code.pdf to Chinese"
# Claude Code will:# - Run convert.py to split into chunks# - Launch 8 parallel subagents per batch# - Each subagent translates one chunk# - Validate all outputs via manifest# - Merge and build all formats
# 4. Outputs appear in:ls clean-code_temp/# chunk0001.md  chunk0002.md  ...  (source)# output_chunk0001.md  ...         (translated)# manifest.json# output.md# book.html# book.docx# book.epub# book.pdf

Resuming an Interrupted Translation

# If translation is interrupted, just re-run the same command:# "translate clean-code.pdf to Chinese"
# The skill detects existing output_chunk*.md files# and skips already-translated chunks automatically.# Only missing or failed chunks are retried.

Changing Output Metadata After Translation

If you need to update the title, author, template, or image assets without re-translating:

# Delete only the final artifacts (keeps translated chunks)cd book_name_temp/rm -f output.md book*.html book.docx book.epub book.pdf
# Re-run merge steppython3 ../scripts/merge_and_build.py \  --temp-dir . \  --title "《New Title》"

Do NOT delete chunk files — those are your translated content. Only delete final artifacts when changing metadata.

Troubleshooting

Diagnosing Chunk Issues

# Check which chunks are missing translationls book_temp/chunk*.md | wc -l          # total source chunksls book_temp/output_chunk*.md | wc -l   # translated chunks so far
# Find missing output chunksfor f in book_temp/chunk*.md; do  base=$(basename "$f" .md)  out="book_temp/output_${base}.md"  if [ ! -f "$out" ] || [ ! -s "$out" ]; then    echo "Missing: $out"  fidone
# Check manifestcat book_temp/manifest.json | python3 -m json.tool | head -30

Configuration Tips

• Chunk size: ~6000 chars per chunk is the default. Smaller chunks = more parallelism but more API calls.
• Concurrency: Default is 8 parallel subagents per batch. Adjust in SKILL.md if hitting rate limits.
• Languages: Add new language codes to the skill triggers and translation prompt in SKILL.md.
• Templates: Customize scripts/template.html and scripts/template_ebook.html for different HTML/ebook styling.

Key Design Principles

1. Isolated context per chunk — each subagent starts fresh, preventing context overflow on long books
2. Hash-based integrity — SHA-256 tracking catches stale or corrupt translated chunks before merging
3. Resumable at chunk granularity — never re-translate what's already done
4. Format-agnostic input — Calibre handles PDF/DOCX/EPUB normalization before the pipeline begins
5. Multiple output formats — single pipeline produces HTML, DOCX, EPUB, and PDF simultaneously