translate-book: translating whole books with parallel agent subagents

The pipeline converts every input to numbered Markdown chunks before translation begins

Every translation job starts at the same point. Calibre's ebook-convert command takes the input file, whether PDF, DOCX or EPUB, and produces an HTMLZ archive. From there the pipeline continues through an intermediate HTML stage and then to Markdown. That Markdown is split into sequentially numbered files, chunk0001.md, chunk0002.md and so on, which become the atomic units of work for the subagents downstream.

One alternative entry point exists for formula-heavy and table-heavy PDFs. MinerU and Marker are listed in the prerequisites as optional preprocessing tools for documents where Calibre extraction renders poorly. When the input already arrives as Markdown, whether from those tools or from another source, the Calibre conversion steps are skipped and chunking begins immediately. That makes the pipeline composable with other extraction tools without requiring a new integration.

Both Calibre and Pandoc are required external dependencies. Neither is bundled or installed automatically by the skill. The prerequisites section links to calibre-ebook.com and pandoc.org but gives no minimum version for either.

8 subagents run in parallel per batch, each holding only one chunk in context

The core mechanism assigns exactly one chunk to each subagent. The default concurrency is 8 per batch. Each subagent operates independently: it opens its assigned file, runs translation in a private context window, and writes the result before exiting. Because every subagent starts fresh, nothing from earlier chunks carries over, and the total size of the source book does not affect how much context any individual subagent must hold.

When a book splits into more than 8 chunks, the pipeline finishes the first batch and then starts the next. API rate limits are the stated reason for that batching constraint, though no configurable wait interval or batch-size key appears in the documentation.

7 target languages appear in the prerequisites section: zh, en, ja, ko, fr, de and es. The list is described as extensible, but how to extend it, whether the subagent prompt needs modification for an unlisted language, and which language codes the pipeline accepts for new entries are not documented.

manifest.json records a SHA-256 hash per chunk; a mismatch stops the merge before bad content enters

Before translation begins, each chunk file's SHA-256 hash goes into manifest.json. After a batch finishes, a validation pass compares every output chunk against its recorded hash and confirms that the source file count and the output file count are equal. A file that did not write fully, or a leftover from a different source version, breaks that comparison and stops the merge before any corrupted content enters the final book.

A second file, run_state.json, handles resumability separately. It categorizes chunks as done or queued, and also marks chunks that must be rerun because a glossary term was revised since they last ran. That selective reprocessing avoids a full restart when only a handful of terms change. A run interrupted by a network failure or a rate limit continues from the last completed chunk on the next invocation, without repeating work that already passed the hash check.

Both files are plain JSON stored under the {book_name}_temp/ directory, so they can be inspected directly when a run behaves unexpectedly.

Installing the skill on Claude Code or Codex requires Calibre, Pandoc and Python 3 first

The installation follows 3 stages. First, Calibre and Pandoc must be at the system level and available on PATH. Second, Python 3 must be present with pypandoc added via pip. pypandoc is required; beautifulsoup4 is optional and described as improving TOC generation for the HTML output.

pip install pypandoc

With those prerequisites in place, the skill is registered with the agent runtime. For Claude Code, the skills add command installs it globally:

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

A manual install clones the repository directly into the Claude Code skills directory instead:

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

For OpenClaw, the install uses that tool's own registry:

openclaw skills install @deusyu/translate-book

Once installed, a translation can be started in Claude Code with a slash command. The quick start section gives this example for a file going to Japanese:

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

In Codex, the skill can be selected automatically when the request matches its description, without an explicit prefix. All output files land under a directory named after the source book. A completed run produces 5 files: output.md, book.html, book.docx, book.epub and book.pdf.

Neighbor context gives each subagent a read-only excerpt from adjacent chunks for pronoun resolution

Splitting a book into independent chunks creates a consistency problem. A pronoun at the start of chunk five may refer to a noun introduced at the end of chunk four, and a subagent operating in complete isolation cannot resolve that reference correctly.

Neighbor context gives each subagent brief text from the 2 surrounding chunks: the chunk just before and the chunk just after. That text is read-only; the translating subagent can inspect it for pronouns and named entities but cannot alter it. The result is that references at chunk boundaries have a better chance of being translated consistently without each subagent needing to hold the full preceding context.

How long those excerpts are, whether the length is configurable, or whether context reaches past the immediately adjacent chunks is not documented. A pronoun chain spanning more than 2 chunk boundaries, or a section heading that divides a sentence, are situations the documentation does not address.

Scanned PDFs and image-only PDFs have no supported path through this pipeline

Calibre's ebook-convert processes PDFs that contain selectable text. A scanned PDF stores pages as rasterized images, not as text, so ebook-convert cannot extract the content the chunker needs. No OCR step appears in the pipeline. MinerU and Marker, the optional preprocessing tools listed in the prerequisites, are described as handling formula-heavy and table-heavy PDFs, meaning PDFs where text is present but the layout is complex. Neither is described as OCR software for image-only documents.

The same boundary applies to other input types. HTML pages not packaged as EPUB, plain text files that are not already Markdown, and audio or video files have no path into the pipeline. A corpus of web articles would need to be packaged into EPUB files or converted to Markdown before the chunker could process them.

One gap worth noting: how the skill handles a PDF whose pages mix selectable text with embedded images is not described. Whether the text portion is extracted and the image portions silently skipped, or whether the conversion fails outright, does not appear in the documentation.

claude_translater used shell scripts; translate-book restructures the same idea as an agent skill with a manifest

The project names claude_translater as its inspiration. The original coordinates the Claude CLI with multiple step scripts in shell, breaking a book into chunks and running translation through those scripts. translate-book departs from that design in three ways the project describes: the workflow runs as an agent skill rather than a set of shell scripts, chunks are translated in parallel by subagents rather than sequentially, and the pipeline adds manifest-driven integrity checks and resumable-run tracking that the original does not include.

The project notes explicitly that the structure and implementation differ enough from claude_translater to make this an independent project rather than a fork. That distinction has a practical edge for a user choosing between the two. The shell-script design of claude_translater may be simpler to inspect and modify without an agent runtime installed. translate-book requires Codex, Claude Code or OpenClaw to be present and working, and the translation logic lives inside the skill rather than in shell scripts a user can read and edit directly.

For a user who already has one of those runtimes running, translate-book adds the manifest layer and parallel execution that a shell-script approach does not provide on its own.

No tagged releases and a single-maintainer contribution model

The repository carries no GitHub releases. There is no tagged version and no version number in the documentation. Anyone who needs a reproducible build must record the commit hash at the time of cloning. The last push was on 2026-09-24, and the repository is not archived.

The contribution guidelines state that pull requests are not the preferred path. Contributors are asked to open a detailed issue first; pull requests may be closed in favor of an issue. The stated reason is that changes need evaluation against the current orchestration rules, chunk and manifest contracts, baseline assets, and release flow in one maintainer-owned context. For a user who finds a bug, the practical path is a GitHub issue that includes the current and expected behavior, the input format, the OS, the Calibre and Pandoc version numbers, and minimal reproduction steps. Those details are requested specifically.

The project is MIT-licensed. The LICENSE file is at the repository root. Contact channels in the documentation include GitHub Issues, an X account at @0xdeusyu, and Telegram groups for Chinese-language discussion.

Editorial conclusion

translate-book suits engineers already running Codex, Claude Code or OpenClaw who need to translate a complete PDF, DOCX or EPUB without managing a translation API directly. The pipeline requires Calibre and Pandoc on PATH before anything else runs, and ebook-convert is where most failures appear for unusually structured documents. Skip it if your source is a scanned or image-only PDF, since there is no OCR step. Before relying on it, run the baseline test from inside tests/.artifacts/ with the included EPUB sample and check that output.md carries the expected language.

Frequently asked questions

Official sources

1. deusyu/translate-book on GitHub
2. Issues
3. License: MIT
4. README