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)
# macOS
brew install --cask calibre
# Linux
sudo apt-get install calibre
# Or download from https://calibre-ebook.com/

# 2. Pandoc
brew install pandoc        # macOS
sudo apt-get install pandoc # Linux

# 3. Python dependencies
pip install pypandoc beautifulsoup4

Verify all tools are available:

ebook-convert --version
pandoc --version
python3 -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

Code	Language
zh	Chinese
en	English
ja	Japanese
ko	Korean
fr	French
de	German
es	Spanish

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 input
python3 scripts/convert.py /path/to/book.epub --olang ja

# For DOCX input
python3 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:

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

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 hashes
manifest = {
    "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 skill
npx skills add deusyu/translate-book -a claude-code -g

# 2. Open Claude Code in your working directory
cd ~/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 step
python3 ../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

Problem	Solution
Calibre ebook-convert not found	Install Calibre; ensure ebook-convert is in $PATH
Manifest validation failed	Source chunks changed — re-run convert.py
Missing source chunk	Source file deleted — re-run convert.py to regenerate
Incomplete translation	Re-run the skill — resumes from last valid chunk
Changed title/template but output unchanged	Delete output.md, book*.html, book.docx, book.epub, book.pdf then re-run merge_and_build.py
output.md exists but manifest invalid	Script auto-deletes stale output and re-merges
PDF generation fails	Verify Calibre has PDF output support; try ebook-convert --help
Empty output chunks	Retry failed chunks; check API rate limits

Diagnosing Chunk Issues

# Check which chunks are missing translation
ls book_temp/chunk*.md | wc -l          # total source chunks
ls book_temp/output_chunk*.md | wc -l   # translated chunks so far

# Find missing output chunks
for 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"
  fi
done

# Check manifest
cat 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