epub-translator

EPUB Translation

Translate English .epub books into Simplified Chinese .epub. Model calls are made by the main agent or subagents in the current chat environment; this skill is not tied to OpenAI, Claude, Gemini, or any specific API.

The script only performs deterministic EPUB engineering processing:

解包 EPUB → 提取正文/目录/元数据文本分块 → agent 翻译 JSONL → 写回 EPUB → 重新打包 EPUB

Quick Start

First split the EPUB into chunks to be translated:

python3 scripts/translate_epub.py prepare book.epub -w work/book-zh

Translate work/book-zh/chunks/*.jsonl, and write the translations into the JSONL file with the same name under work/book-zh/translated/ .

Check whether all translations are complete:

python3 scripts/translate_epub.py check -w work/book-zh

Generate the Chinese EPUB:

python3 scripts/translate_epub.py build -w work/book-zh -o book.zh-Hans.epub

Translation Chunk Format

prepare generates JSONL files from the body XHTML, EPUB 3 nav.xhtml、EPUB 2 toc.ncx and OPF title metadata, with one text node per line:

{"id":"t000001","source":"Chapter 1","translation":""}

When translating, you must:

• Keep one record per line in the JSONL.
• Preserve id and source。
• Only fill in the translation field.
• Do not add explanations, summaries, notes, or extra fields.
• Do not merge, split, or reorder records.
• If source contains tag placeholders such as [t:0]、[t:1] ,translation must be preserved in the same quantity and order; these placeholders represent EPUB inline tags such as links, footnotes, italics, and bold.

Example after translation:

{"id":"t000001","source":"Chapter 1","translation":"第一章"}

Agent Workflow

1. Confirm that the input is a .epub file, and determine the output path; by default it is recommended to <原文件名>.zh-Hans.epub。
2. Run prepare, generating manifest.json、chunks/、translated/ and the unpacked source/; the extraction scope includes the body, table of contents, and book title metadata.
3. Establish a glossary: Before translating, first read/scan all the text content to be translated, identify the book's high-frequency core technical terms, proper nouns, main character names, or specific phrases, and create a unified terminology reference table in the working directory (such as glossary.md), to ensure consistency of terminology in subsequent translation.
4. Translate by chunk:
   • For small books, the main agent can process them one by one chunks/*.jsonl。
   • For large books, they can be assigned in parallel to subagents, with each subagent handling only a few chunks.
   • Before translating, each subagent must read glossary.md, and maintain terminology consistency according to the translated names in it.
   • Subagent outputs must be written to translated/chunk-xxxx.jsonl, do not modify source/。
5. Run check, ensuring that all id have non-empty translation, and that there are no duplicate IDs, unknown IDs, blank translations, or placeholder mismatches.
6. Run build, write the translations back into the body, table of contents, and metadata, update the EPUB language code to zh-Hans , and then repackage.
7. Spot-check the output EPUB: the table of contents page, preface, first chapter, chapters with footnotes, and chapters with images.

Translation Principles

• Target language: Simplified Chinese by default.
• Preserve the original meaning, tone, paragraph boundaries, and reading rhythm.
• Personal names, brand names, and proper nouns may remain in English; use natural Chinese translations when necessary.
• Keep terminology consistent; do not repeatedly change translations within the same chunk.
• Do not translate URLs, email addresses, code, commands, file names, or anchors.
• Do not omit content; do not skip it because the text is repetitive, dull, or short.
• Do not add explanations, summaries, headings, or translator's notes that are not in the original book.

CLI commands

Command	Description
prepare <book.epub> -w <work-dir>	Unpack EPUB and extract JSONL chunks to be translated
check -w <work-dir>	Check whether the translation in translated/ is complete
build -w <work-dir> -o <output.epub>	Write back the translation and repack the EPUB

Common options:

Option	Description
--source-language	Source language tag, default English
--target-language	Target language tag, default Simplified Chinese
--target-language-code	Target language code written to EPUB metadata, default zh-Hans
--chunk-chars	Approximate number of source text characters per chunk, default 8000
--force	prepare Overwrite the existing working directory when
--allow-missing	build Allow missing translations and keep the original text when

Failure handling

Symptom	Handling
work directory already exists	Switch to another working directory; if overwriting is confirmed, use --force
MISSING greater than 0	Fill in the missing or empty ones in translated/*.jsonl missing or empty translation
duplicate id	Remove duplicate records and keep only the one for that id one translation for
unknown id	Remove extra records not in manifest.json extra records in
blank translation	Fill in the corresponding translation, do not write only spaces
The output EPUB cannot be opened	Confirm that the input EPUB itself can be opened; rerun build
Some chapters are still in English	Run check, and search for translated/ empty translation fields in
The reader table of contents is still in English	Confirm that the EPUB's nav.xhtml or toc.ncx already appears in manifest.json 's documents , and check whether the corresponding chunk has been translated
A placeholder mismatch is reported during build	Retranslate the corresponding record to ensure that [t:n] the number and order of placeholders match source exactly
The sub-agent output breaks JSONL	Have the sub-agent rewrite only the corresponding chunk, and keep one JSON object per line

Installation

The script uses only the Python standard library, so no third-party dependencies need to be installed.