Translate Book Skill Review: Whole Books in Claude Code
A. Frans
Published November 16, 2026
Table of Contents
Translate Book splits an EPUB, PDF or DOCX into roughly 6,000-character chunks, hands each chunk to its own subagent, and stitches the results back into HTML, DOCX, EPUB and PDF. It has 2,420 GitHub stars, an MIT license, and a commit from November 7, 2026. For a translator or publisher who wants a full machine draft of a book inside Claude Code or Codex, it's the most complete skill we've found.
What comes out is a well-engineered first draft, and the people who'll get the most from it are the ones who plan to edit that draft.
We reviewed it from the repository itself on November 16, 2026: the README, SKILL.md, and the Python scripts convert.py, merge_and_build.py, calibre_html_publish.py and glossary.py. We didn't translate a full book for this piece, so there are no quality scores below. What follows is what the skill does, what it needs, what it costs you to run, and where it's likely to break.
| Translate Book | |
|---|---|
| Repo | deusyu/translate-book |
| Directory page | /skills/translate-book |
| Agents | Claude Code, Codex, OpenClaw |
| Input | PDF, DOCX, EPUB, Markdown |
| Output | output.md, book.html, book.docx, book.epub, book.pdf |
| Languages listed | zh, en, ja, ko, fr, de, es (extensible) |
| Default target | Chinese (zh) |
| Parallelism | 8 subagents per batch by default |
| Needs | Calibre, Pandoc, Python 3 with pypandoc |
| Cost | Free skill; translation uses your agent plan or API bill |
1. Install the prerequisites first
The skill orchestrates; Calibre and Pandoc do the file conversion. Install both before anything else, then the Python package:
pip install pypandoc
pip install beautifulsoup4 # optional, better table of contents
Make sure ebook-convert (Calibre's command-line tool) is on your PATH. "Calibre ebook-convert not found" is the first error in the project's troubleshooting table for a reason.
2. Install the skill
For Claude Code:
npx skills add deusyu/translate-book -a claude-code -g
Or clone it by hand:
mkdir -p ~/.claude/skills
git clone https://github.com/deusyu/translate-book.git ~/.claude/skills/translate-book
Codex users swap -a claude-code for -a codex. OpenClaw users run openclaw skills install @deusyu/translate-book.
3. Run it on a book
Ask in plain language, or use the slash command:
/translate-book translate /path/to/book.epub to Japanese
Say the target language every time. The default is Chinese, and a run that quietly translates your English novel into Chinese wastes a lot of tokens.
The pipeline then runs on its own:
1. Calibre converts the book to HTMLZ, which becomes Markdown, which is split into chunks. A manifest.json stores a SHA-256 hash of each source chunk. 2. The skill samples five chunks (first, last, and three in between), pulls out proper nouns and recurring terms, and writes glossary.json. 3. Subagents translate chunks in batches of eight. Each one gets its chunk, a table of glossary terms that appear in it, and about 300 characters from the chunks before and after, so pronouns and names have some context. 4. Failed chunks are retried once. The merge refuses to run if any output is missing, blank, stale against the manifest, or missing a footnote marker its source had. 5. Pandoc builds HTML with a floating table of contents, and Calibre produces DOCX, EPUB and PDF.
Everything lands in {book_name}_temp/.
4. Fix the glossary, not the book
Pasting chapters into a chat window gives you nothing like this step. Because every chunk is translated in a fresh context, the same character name can drift across a 100-chunk book. The glossary is the fix, and you can edit it.
Open glossary.json, correct the target for any term you don't like, and re-run the skill. A run-state file records which glossary terms each chunk used, so only the chunks that contain a changed term get re-translated. On a long book that saves most of the cost of a second pass.
For a handful of bad sentences, edit the matching output_chunkNNNN.md file directly, run python3 scripts/run_state.py record <temp_dir> chunkNNNN, then rebuild with merge_and_build.py. Don't edit output.md; the next merge rebuilds it from the chunks and your edits vanish.
5. Handle technical PDFs separately
Calibre reflows PDF text by position, which is fine for a novel and bad for a textbook. Formulas break into fragments, tables collapse to one cell per line, and two-column pages interleave. The README's answer is to extract the PDF with MinerU or Marker first and feed the skill the Markdown:
pip install -U "mineru>=4.0,<5"
mineru-kit parse paper.pdf -o paper.md
Formulas then survive as LaTeX and render as MathML in the HTML, PDF and most EPUB readers. DOCX is the exception: Calibre can't typeset MathML there, so formulas show as flattened text followed by their TeX source. If your client wants Word files for a maths-heavy book, plan on fixing equations by hand.
6. Budget the tokens before you start
The skill doesn't call any model API itself. Translation runs inside your own agent, so every chunk is a subagent call billed to your Claude plan or API account. A book of about 600,000 characters becomes roughly 100 chunks, and each chunk is read once and written once, plus the glossary pass and any retries.
On a subscription plan, eight parallel subagents can burn through a usage window fast. A lower concurrency value spreads the load if you keep hitting limits.
The repo gives you a cheap way to find out what a run costs before you risk a real manuscript. It ships three public-domain test books under tests/baselines/. The smallest, The Legend of Sleepy Hollow from Project Gutenberg, splits into about 21 chunks, and the project's notes call it the cheapest input that still exercises every stage. Alice's Adventures in Wonderland (Standard Ebooks edition) is the full baseline at roughly twice that, and Diligent Dick runs about 57 chunks because its many short chapters create tiny heading-only chunks.
Translate Sleepy Hollow into your target language first. You'll see how much of your usage window 21 chunks take, how the glossary handles a name that appears as "Headless Horseman", "Galloping Hessian" and "spectre", and whether the EPUB opens cleanly in your reader. Multiply from there before you start a 400-page book.
Security: what it runs and what it touches
We read the four main scripts. They call subprocess only to run Calibre's command-line tools, and we found no network requests in them. That matches the README's statement that the project doesn't call model APIs.
The skill's frontmatter allows Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion. That's a broad set, which a multi-step file pipeline needs, but it means a compromised future version could do a lot. Pin to a commit you've read rather than pulling main blindly, and see our skill audit guide for the checklist.
Two operational cautions. --cleanup permanently deletes the chunks and inputs, which rules out later fixes, so use it only when the book is done. And the project maintainer prefers GitHub issues over pull requests, so expect fixes to come from the maintainer rather than from community patches.
One legal point that's yours, not the skill's: translating a book you don't hold rights to and distributing it is still infringement. The three test books in the repo are all public domain, which is another reason to practise on them.
Verdict: install it if you'll edit the output
For professional translators, Translate Book is a fast way to get a consistent first draft of a long text, with a glossary you control and outputs your editor can open. The chunk-and-merge validation is better engineered than most skills we review. For anyone hoping to publish the raw output, it won't replace a human pass, and the README doesn't claim it will.
Compare it with the skills in our roundup for translators, which cover shorter documents and glossary spreadsheets, and with DeepL and Smartcat for CAT-tool workflows. Our full list for translators has the rest.
FAQ
Is Translate Book free?
The skill is free and MIT-licensed. Translation runs inside your own agent, so you pay through your Claude Code, Codex or OpenClaw plan or API usage. Long books mean many subagent calls.
Which languages does Translate Book support?
The README lists Chinese, English, Japanese, Korean, French, German and Spanish, and calls the list extensible. Chinese is the default target, so name your target language in every request.
Can it translate scanned PDFs?
The pipeline expects extractable text. Text-based PDFs work through Calibre, and formula- or table-heavy PDFs work better through MinerU or Marker first. A scanned image-only PDF needs OCR before the skill can do anything with it.
How does it keep names consistent across chapters?
It builds a glossary from five sampled chunks, injects matching terms into each chunk's prompt, and gives each subagent short excerpts from neighbouring chunks. Edit glossary.json and re-run to re-translate only the affected chunks.
Does it work in Claude Code without Codex?
Yes. It installs as a Claude Code skill with npx skills add deusyu/translate-book -a claude-code -g, and runs from a plain request or the /translate-book slash command.
Share this article
⚙Related Tools
📄Related Articles
Get More AI Tool Guides
New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.