epub-bilingual-converter-skill#

Overview#

Use this skill to convert an EPUB into a bilingual EPUB through four separated stages:

1. Extract structure with scripts/extract.py.
2. Estimate translation token budget with scripts/estimate_tokens.py.
3. Fill only target-language fields in extraction.json.
4. Assemble the bilingual EPUB, summary text files, and report.txt with scripts/assemble.py.

Keep extraction, translation, and assembly responsibilities separate. Extraction must not translate. Assembly must not invent translations. Translation must not alter source fields or structure.

Inputs#

Require an EPUB file and target language. If the user omits the target language, ask for it before processing.

Use an output directory supplied by the user. If none is supplied, create a sibling directory named output beside the EPUB.

If the user provides an EPUB path for translation or conversion, create or refresh extraction.json from that EPUB before estimating. If the user explicitly provides an extraction.json path, estimate and continue from that file instead of re-extracting.

Dependencies#

Before running the scripts, ensure Python 3 is available and install the required parser libraries if they are missing:

bash

python3 -m pip install beautifulsoup4 lxml

The scripts use only Python standard libraries plus beautifulsoup4 and lxml.

Quick Start#

bash

python3 scripts/extract.py /path/to/input.epub /path/to/output --target-language Chinese

Estimate the translation budget before translating:

bash

python3 scripts/estimate_tokens.py /path/to/output/extraction.json

Show the estimate to the user and wait for explicit confirmation. Only after the user confirms, fill target_language fields in /path/to/output/extraction.json, then run:

bash

python3 scripts/assemble.py /path/to/output/extraction.json

The final outputs are:

• /path/to/output/bilingual_<input filename>.epub
• /path/to/output/summary/*.txt
• /path/to/output/report.txt

Stage 1: Extract#

Run scripts/extract.py. It reads EPUB files as zip archives, finds the OPF path via META-INF/container.xml, follows OPF spine order, classifies HTML/XHTML pages, extracts article-like pages, copies first images to summary/, and writes UTF-8 extraction.json.

The extractor supports:

• Magazine/news pages with ul.calibre_feed_list and data-testid="article-title".
• Book/chapter pages with headings such as h1.chapter_title, h1.chapter_head, or content-heavy spine pages.
• TOC-like pages, cover/title/copyright pages, illustration lists, indexes, ads, and miscellaneous pages as non-article pages.

For unfamiliar EPUB sources, inspect the archive before changing logic:

bash

python3 -c "import zipfile; z=zipfile.ZipFile('/path/to/input.epub'); print('\n'.join(z.namelist()))"

If extraction quality is poor, adjust page classification, title extraction, paragraph filtering, TOC detection, or image path handling in scripts/extract.py after observing the source structure.

Stage 2: Estimate Translation Tokens#

For every EPUB translation or conversion request, run scripts/estimate_tokens.py on extraction.json to estimate the translation-stage token budget before translating:

bash

python3 scripts/estimate_tokens.py /path/to/output/extraction.json

When the user provides an EPUB, create or refresh extraction.json from the EPUB first. When the user explicitly provides extraction.json, use that file directly.

After showing the estimate report, stop and ask the user to confirm before starting translation. Do not begin filling translations until the user explicitly confirms after seeing the estimate. Valid confirmations include short replies such as 继续, ok, 可以, 确认, 开始翻译, proceed, or go ahead.

The user's initial request to translate or convert an EPUB is not enough to bypass this gate. The confirmation must happen after the concrete estimate report is shown.

If the user only asks for token estimation and does not ask to translate or convert, run extraction if needed, show the estimate, and stop without asking for translation confirmation.

The estimator is a lightweight character heuristic, not a tokenizer-exact counter. It estimates only translation-stage model usage:

• Source paragraph, title, section, and summary-source input tokens.
• Target paragraph, title, section, and summary output token range.
• Prompt/JSON overhead.
• Retry/rework buffer.
• Recommended paragraph batch count using source-character batches.

It does not estimate local EPUB extraction, parsing, or assembly work because those are local scripts. It also does not output cost amounts.

Default estimation behavior:

• Input is extraction.json, not the raw EPUB.
• Scope is the full extraction, even if some articles are already translated.
• Batch recommendation uses --max-source-chars 8000.
• Retry/rework buffer is --retry-buffer 0.15.
• The report includes a total overview and the largest 5 articles by source characters.

Useful options:

bash

python3 scripts/estimate_tokens.py /path/to/output/extraction.json --max-source-chars 6000 --retry-buffer 0.2 --top 10

Stage 3: Fill Translations#

Translation execution policy:

• Default to translating with the current agent/session that invoked this skill.
• For every EPUB translation or conversion request, perform Stage 2 token estimation first and wait for the user's post-estimate confirmation before translating.
• Do not call external translation or LLM APIs, CLI agents, background model runners, or provider SDKs unless the user explicitly asks for that provider/tool or explicitly approves using it.
• Do not infer permission from environment variables, installed CLIs, available credentials, or a large translation workload.
• If the translation is too large for one response, process it in batches within the current session, saving progress after each article or batch.
• If using an API would materially improve speed or reliability, ask before switching execution methods and name the provider/tool that would be used.
• If the user asks to "use current skill" or "directly translate", treat that as permission to use this skill's extraction and assembly scripts, not permission to use third-party translation APIs.

For large EPUBs, prefer a resumable batch workflow instead of trying to translate the whole book in one pass:

1. Generate deterministic translation batches from extraction.json.
2. Translate one batch at a time in the current session.
3. Save each batch result separately.
4. Validate batch identity, source hashes, item counts, and non-empty translations before merging.
5. Save progress after each successful batch so interrupted work can resume from the next pending or failed batch.

See docs/superpowers/specs/2026-05-31-resumable-translation-batches-design.md for the full testable design.

Read extraction.json and fill only these fields for each article:

• title_dest_language
• section_dest_language
• translated_paragraphs
• summary_dest_language

Do not modify:

• num
• title
• section
• href
• paragraphs
• plain_text
• image_filename

Translation Quality Pipeline: Faithfulness, Elegance, Readability#

Translate in three focused passes instead of trying to satisfy every quality goal at once:

text

Faithfulness (信) -> Draft A
Elegance (雅) checks and refines Draft A -> Draft B
Readability (达) checks and refines Draft B -> Final translation

Keep paragraph count, paragraph order, facts, and meaning unchanged across all passes. If a later pass conflicts with faithfulness, revert to the faithful wording.

Pass 1: Faithfulness#

Translate each source paragraph into Draft A while focusing only on faithfulness:

• Do not omit source information.
• Do not add information absent from the source.
• Do not distort facts, views, logic, or tone.
• Preserve numbers, dates, names, terms, and limiting conditions.
• Preserve causality, contrast, progression, comparison, and other logical relations.
• Keep technical terms, proper nouns, and repeated expressions consistent.
• Do not change the source judgment for the sake of fluency or polish.

After this pass, Draft A should be structurally complete and faithful, even if the wording is not yet polished.

Pass 2: Elegance#

Review Draft A and generate Draft B by improving elegance while preserving faithfulness:

• Keep expression restrained, natural, and rhythmic.
• Do not pile up decorative language.
• Do not over-literarize.
• Do not rewrite beyond the source.
• Match the source genre and tone.
• Keep technical writing accurate and clear.
• Keep journalism objective and fluent.
• Preserve flavor in essays when appropriate.
• Preserve stance and force in opinion writing.

After this pass, Draft B should sound more refined but must not change source meaning, add commentary, or lose details from Draft A.

Pass 3: Readability#

Review Draft B and generate the final translation by improving target-language readability:

• Avoid obvious translationese.
• Follow target-language idiom.
• Keep sentences readable and logic clear.
• Reorder long sentences when needed.
• Make phrasing natural without changing meaning.
• Ensure target-language readers can understand the passage easily.

Only write the final pass into translated_paragraphs. Do not expose Draft A or Draft B in extraction.json.

Hard constraint:

text

len(translated_paragraphs) == len(paragraphs)

Each translated_paragraphs[i] must translate exactly paragraphs[i]. Do not merge, split, reorder, omit, add commentary, add notes, or put summaries/titles inside paragraph translations.

Bilingual reading order must always be source language first, target language second. For every paragraph pair, render or preview paragraphs[i] before translated_paragraphs[i]. For titles and TOC labels, use {source title} | {target title}. Do not place target-language content before the corresponding source-language content in bilingual previews or EPUB body content.

Generate summary_dest_language from plain_text in the target language. Default to 150-300 target-language characters when the article is long; shorter is acceptable for short articles.

After each article, self-check:

• Paragraph counts match.
• No empty translations exist.
• No source information is omitted or invented.
• Logic, tone, names, terms, and section translations are consistent.
• The summary is accurate and separate from paragraph translation.

When only doing the translation stage, output valid JSON only, without Markdown fences or explanation.

Stage 4: Assemble#

Run scripts/assemble.py after all translation fields are complete:

bash

python3 scripts/assemble.py /path/to/output/extraction.json

The assembler:

• Rewrites article titles as {source title} | {target title}.
• Inserts <p class="dest_translation">...</p> after each source paragraph.
• Updates TOC and index link text when source titles/sections can be matched.
• Skips ad pages.
• Preserves covers, images, CSS, fonts, OPF, NCX, and other non-ad resources.
• Injects .dest_translation CSS once into HTML/XHTML heads.
• Writes one summary text file per article.
• Writes report.txt with EPUB title, paths, target language, article/image counts, missing first images, and untranslated/incomplete articles.

If assemble.py reports incomplete translations, fix extraction.json instead of changing source fields or bypassing validation.

Output Contract#

extraction.json uses this shape:

json

{
  "epub_title": "...",
  "input_epub": "/abs/path/to/input.epub",
  "output_dir": "/abs/path/to/output",
  "target_language": "Chinese",
  "total_articles": 1,
  "articles": [
    {
      "num": 1,
      "title": "Source Title",
      "section": "Source Section",
      "href": "relative/path/article.xhtml",
      "paragraphs": ["Source paragraph"],
      "plain_text": "Source plain text, max 8000 chars",
      "image_filename": null,
      "title_dest_language": null,
      "section_dest_language": null,
      "translated_paragraphs": null,
      "summary_dest_language": null
    }
  ]
}

Validation#

Minimum validation before delivery:

bash

python3 scripts/extract.py /path/to/input.epub /path/to/output --target-language Chinese
python3 scripts/estimate_tokens.py /path/to/output/extraction.json
python3 -m json.tool /path/to/output/extraction.json >/dev/null
python3 scripts/assemble.py /path/to/output/extraction.json

For assembly validation without real translation, use temporary placeholder values only in a disposable copy of extraction.json. Do not present placeholder output as a completed translation.