Translate Book
Translate entire PDF/DOCX/EPUB books into any language with parallel subagents, glossary-enforced terminology, and multi-format output.
SKILL.md only reads/writes a user-specified working directory, asks the user when parameters are missing, uses fingerprints and manifests to prevent stale reuse, applies --cleanup only after success and omittable; no network exfiltration or overreach found. Deducted for: broad allowed-tools including Bash/Agent, and external effects (temp-dir deletion, overwriting export files) lacking explicit user confirmation.
Failure modes (blank chunks, manifest failures, fingerprint mismatch, Calibre-missing degradation) are thoroughly documented; unit tests cover convert/chunk_context/calibre wrapper and CI runs them. Deducted for: the core orchestration path (subagent translation, meta merge, run_state planning) is untested and script sources were not provided for this review; static review caps at 10.
Target scenario (whole-book translation to zh/en/ja etc.), I/O formats, non-fit boundaries (EPUB cover extraction explicitly out of scope), and trigger descriptions are clear; bilingual docs; dependencies are local Calibre/Pandoc plus the LLM runtime, no unreachable overseas service. Deducted for: semantic triggers rely mainly on description matching, and no declared limits for huge or scanned PDFs.
Well-layered docs (SKILL.md, bilingual READMEs, AGENTS.md/CLAUDE.md), MIT license, git-tag version anchors, explicit maintainer workflow and known issues (Calibre 7.6 EPUB bug). Deducted for: no standalone CHANGELOG, release flow depends on .claude/commands/release.md not present in evidence, and PR-unfriendly contribution policy may hurt sustainability.
Claimed whole-book parallel translation, multi-format output and terminology consistency have clear marginal value over manual work and the workflow is self-consistent. Deducted for: no committed representative real-book output as evidence; the author admits full-book organic quality validation is future work (Phase 4); static review cannot confirm outputs are directly usable.
A CI workflow runs unittest and committed tests cover key sub-paths (page-number cleanup, source fingerprinting, neighbor context); issue/PR references are traceable. Deducted for: tests are mock-driven unit tests; the orchestration main path and end-to-end quality lack independently reproducible evidence; nothing was executed in this static review.
- Static review only — no code was executed: the orchestration main path (subagent translation, meta merge, run_state planning) has no test coverage; validate with a small file before a real book run.
- allowed-tools includes Bash and Agent (broad); --cleanup deletes intermediate files — omit it explicitly if you need intermediates.
- Ubuntu's Calibre 7.6.0 has a known EPUB generation bug (disclosed by the author); EPUB output may fail, and after changing title/templates you must delete stale artifacts manually.
- Translation quality depends on the underlying LLM; the author acknowledges whole-book terminology/fluency validation is not done — human review is required for important books.
- Local Calibre, Pandoc and Python dependencies are required; missing pieces degrade individual output formats silently — watch the format-failure summary in the final report.
What does this skill do, and when should you use it?
translate-book is an agent skill for Codex, Claude Code, and OpenClaw that translates entire PDF, DOCX, or EPUB books into a target language (Chinese by default; en, ja, ko, fr, de, es also documented). It converts the source with Calibre into chunked Markdown, then farms each chunk to an isolated subagent running in parallel, keeping names, pronouns, and terminology consistent across the book via a hand-editable glossary, neighbor excerpts, and per-chunk metadata feedback. Outputs pass SHA-256 manifest validation before being merged and rebuilt into HTML, DOCX, EPUB, and PDF with Pandoc and Calibre. MIT-licensed, and explicitly an independent rewrite inspired by wizlijun/claude_translater, not a fork.
The skill runs a multi-step pipeline: 1) scripts/convert.py calls Calibre (ebook-convert via HTMLZ) to convert PDF/DOCX/EPUB into Markdown split into ~6000-char chunks (chunk0001.md, ...), writing manifest. (per-chunk SHA-256) and source_fingerprint.; 2) it samples first/last/middle chunks to extract proper nouns into a hand-editable glossary. (v2, with aliases, gender, confidence), and glossary.py counts frequencies and emits per-chunk term tables; 3) run_state.py plans selective re-translation, skipping chunks whose outputs and glossary terms are unchanged; 4) batches of up to 8 subagents by default each translate one chunk with an injected term table and ~300-char read-only previous/next excerpts, emitting output_chunkNNNN.meta. that merge_meta.py conservatively merges into the glossary at batch boundaries; 5) merge_and_build.py validates 1:1 outputs, matching hashes, and no blank chunks, merges to output.md, generates HTML with a floating TOC via Pandoc, then DOCX/EPUB/PDF via Calibre, with --cover and --export-name options.
- An indie translator or publisher with an English EPUB who wants a low-cost Chinese edition delivered as EPUB/DOCX
- A technical reader who only has a PDF published in another language and wants the whole book in their native language before deep reading
- A translation team producing a first-pass machine draft for human polish — the glossary is hand-editable and only affected chunks get re-translated
- Long-running serialized projects needing resumability: interrupted runs skip completed chunks, and a swapped source file aborts via fingerprint mismatch instead of silently reusing stale chunks
- Localization work where names, places, and terms must stay consistent across 100+ chunks, avoiding drift from session-by-session translation
What are this skill's strengths and limitations?
- One isolated subagent per chunk (8 concurrent by default) avoids the context accumulation and output truncation typical of single-session whole-book translation
- Thorough terminology-consistency engineering: sampled glossary, frequency counting, per-chunk hard constraints, sub-agent metadata feedback, and selective re-translation after hand edits
- Resumable with integrity guarantees: manifest SHA-256 validation, source fingerprinting, automatic single retry for blank/missing chunks
- One pipeline yields Markdown/HTML/DOCX/EPUB/PDF, with explicit prerequisites and a detailed troubleshooting table
- Clean design principles: scripts do bookkeeping, LLMs do semantic merging, single writer for shared state
- Heavy local dependencies: Calibre, Pandoc, Python 3, and pypandoc must all be installed; any missing piece breaks format conversion
- Parallel per-chunk translation implies substantial token/API cost for chunk-heavy books; no usage estimates are provided
- EPUB covers must be passed explicitly via --cover; auto-extraction from EPUB is explicitly out of scope
- Quality is validated only against checked-in baseline sample books (e.g., standard-alice.epub); no organic real-book quality evaluation is published, and Phase 4 bootstrap warm-up remains experimental
- Unconventional contribution flow: the maintainer asks for issues before PRs and may close pull requests
- Neighbor context and glossary mechanisms mitigate but do not eliminate cross-chunk pronoun/gender errors; the README roadmap admits full-book organic validation is future work
How do you install this skill?
Prerequisites: Codex, Claude Code, or OpenClaw installed and ready to run skills; Calibre (ebook-convert on PATH); Pandoc; Python 3 with pip install pypandoc (optional beautifulsoup4 for better TOC). Install via: Codex — npx skills add deusyu/translate-book -a codex -g, or git clone https://github.com/deusyu/translate-book.git ~/.agents/skills/translate-book; Claude Code — npx skills add deusyu/translate-book -a claude-code -g, or clone to ~/.claude/skills/translate-book; OpenClaw — openclaw skills install @deusyu/translate-book. Restart Codex if the skill does not appear.
How do you use this skill?
In Claude Code / OpenClaw, just ask the agent: translate /path/to/book.pdf to Chinese, or use the slash command /translate-book translate /path/to/book.pdf to Japanese. In Codex, enter $translate-book Translate /path/to/book.pdf into Chinese. (Codex can also auto-select the skill when your request matches its description.) Mention optional parameters in your request: target language (default zh), concurrency (default 8), a custom temp root, an EPUB cover image, an export alias name, and any custom translation instructions. Outputs land in {book_name}_temp/: output.md, book.html (floating TOC), book.docx, book.epub, book.pdf.
How does this skill compare with similar options?
The README names wizlijun/claude_translater as its inspiration: the original uses shell scripts as the entry point, coordinating the Claude CLI across step scripts. This project restructures that as an agent skill with parallel subagent translation, plus manifest-driven integrity checks, resumable runs, and unified multi-format output — the author stresses the structure and implementation differ significantly, making it an independent project rather than a fork.