bilingual-epub-toolkit 0.1.2

Live demo · 中文说明 · Installation · Usage · Translation · Limitations

Builds facing-text bilingual EPUBs. Each paragraph is followed by its translation, blurred until tapped, so the original can be read first and the translation consulted only when needed.

Works with any standard EPUB and any language pair. Chapter structure and paragraph pairing are derived from the files themselves — no per-book configuration. All processing is local.

• merge two monolingual editions into one bilingual book
• split a bilingual book back into separate languages
• remerge an existing bilingual book with different settings
• translate the missing side via a model API, or via a coding agent
• Command line, terminal wizard, and local web interface, in English or Chinese

Installation

pip install bilingual-epub-toolkit

Chinese Traditional ↔ Simplified conversion requires opencc:

pip install "bilingual-epub-toolkit[chinese]"

Requires Python 3.9 or later. The only runtime dependency is lxml.

Three commands are installed:

Interface language follows the system locale and can be set with --lang en or --lang zh.

Quick start

Two sample books ship with the repository:

bilingual-epub merge --a examples/sample-en.epub --b examples/sample-fr.epub --out demo.epub

Open demo.epub in Apple Books or any EPUB 3 reader. The samples are an original short story written for this project, so no third-party rights are involved. A hosted instance is available at epub.starry-files.duckdns.org for trying the tool without installing it; uploads there are capped at 25 MB and deleted after 30 minutes.

Usage

merge

Combine two monolingual editions:

bilingual-epub merge \
  --a english.epub --b french.epub --out bilingual.epub \
  --blur-side b --blur 0.25em

A per-chapter table is printed after each merge, reporting how many paragraphs paired one to one.

split

Separate a bilingual book by language:

bilingual-epub split --in bilingual.epub --out-dir ./split/ --langs en,fr

Language is read from each block's lang attribute. Omitting --langs writes out every language found.

remerge

Re-render an existing bilingual book with different settings:

bilingual-epub remerge --in old.epub --out new.epub --blur-side a --blur 0.35em

Equivalent to a split followed by a merge. Also converts bilingual books from other sources into this tap-to-reveal format.

Translation

When only one edition exists, the second can be generated. Both routes produce a translation with the same block count and order as the source, so the subsequent merge pairs every paragraph exactly.

With a coding agent

Installs a skill that lets an agent such as Claude Code drive the toolkit, translating on an existing subscription rather than a metered API:

bilingual-epub skill      # writes .claude/skills/bilingual-epub/SKILL.md

The skill file is also available from the hosted instance.

The underlying commands can be used directly:

bilingual-epub export-text --in book.epub --out book.json
# translate book.json into translated.json
bilingual-epub import-text --export book.json --text translated.json \
    --out book.zh.epub --lang zh

import-text accepts a JSON array of strings, a JSON object with a blocks list, or plain text with one block per line. Files whose block count differs from the source are rejected.

With a model API

bilingual-epub translate --in book.epub --out book.zh.epub --to zh \
    --base-url https://api.deepseek.com/v1 --api-key "$KEY" --model deepseek-chat

Credentials may also be supplied through BILINGUAL_API_KEY, OPENAI_API_KEY or ANTHROPIC_API_KEY. Batches returning the wrong number of blocks are retried, then subdivided, and are never accepted as-is.

Self-hosting

The web interface defaults to a single trusted user on localhost. --public adapts it for a shared host:

bilingual-epub-web --public --port 8799

Public mode rejects server-side file paths, isolates each visitor's files, rate-limits by address, caps uploads at 25 MB, and removes idle sessions after 30 minutes (--ttl).

Cloudflare Turnstile can be enabled to filter automated traffic while keeping the service open to anyone:

export TURNSTILE_SITEKEY=0x...
export TURNSTILE_SECRET=0x...
bilingual-epub-web --public

Jobs are then verified before running, and refused if Cloudflare is unreachable. Without keys, no widget is rendered and no verification occurs.

How it works

Chapter boundaries are located by reading the EPUB container, OPF, manifest and spine, then selecting the heading level that recurs at chapter frequency.

Paragraph pairing uses Gale–Church alignment: a length-based statistical model solved by dynamic programming, weighted so that co-occurring headings anchor the sequence. It handles one-to-one pairs as well as paragraphs split or merged in translation.

Every output block carries a lang attribute, which is what allows split to reverse a merge. The tap-to-reveal behaviour uses CSS :target with a small progressive-enhancement script, degrading to plain visible text where neither is supported.

Limitations

No EPUB files are included in this repository apart from the generated samples, and *.epub is gitignored.

Related projects

BookAlign attacks the same pairing problem from the other side: multilingual embeddings (LaBSE) plus dynamic programming, comparing what paragraphs mean rather than how long they are. That reaches the case the table above cannot — a pairing that is wrong but unambiguous, where the lengths happen to line up and a length model stays confident. It is aimed at novels, particularly Japanese originals against Chinese translations, and it runs a review-first workflow rather than one pass end to end.

The two are complementary. This one needs no model and runs anywhere; that one reads the text, at the cost of a local LaBSE model and realistically a GPU. If your two editions differ enough that length alone mispairs them, start there.

Development

git clone https://github.com/StarryGuli/bilingual-epub-toolkit.git
cd bilingual-epub-toolkit
pip install -e ".[dev,chinese]"
pytest && ruff check .

Test fixtures are synthetic EPUBs constructed in code rather than checked-in book files; see tests/conftest.py. Coverage includes the three operations end to end, both cover image formats, the translation round trip against a stub API, public-mode isolation and rate limiting, and the error paths.

Coverage and conventions are described in CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.