EPUB Translate
Workflow
- One-time setup (writes
.skills-data/epub-translate/.env): scripts/epub-translate setup
- Extract translation units:
scripts/epub-translate extract --epub /path/book.epub
- Translate via OpenAI API:
scripts/epub-translate translate --job-dir <job-dir> --target-lang <bcp47> [--fraction 0.1]
- Apply + repack:
scripts/epub-translate apply --job-dir <job-dir> --translations <job-dir>/translations.jsonl --target-lang <bcp47> --out-epub /path/book.<bcp47>.epub
- Optional: validate output:
scripts/epub-translate validate --epub /path/book.<bcp47>.epub
Commands
scripts/epub-translate setup:
- Prompts for
OPENAI_API_KEY (saved to .skills-data/epub-translate/.env).
- Prompts for default
OPENAI_MODEL (e.g. gpt-5.1, gpt-5-mini).
scripts/epub-translate extract ...:
- Unzips the EPUB into a per-run job dir under
.skills-data/epub-translate/tmp/.
- Parses
META-INF/container.xml → package document (.opf) → manifest/spine.
- Extracts XHTML
<head><title> and leaf block-level XHTML fragments (inner HTML) in reading order into units.jsonl.
- Optional: include OPF
dc:title via --include-opf-title.
scripts/epub-translate translate ...:
- Reads
<job-dir>/units.jsonl and writes <job-dir>/translations.jsonl.
- Uses the OpenAI Responses API (
https://api.openai.com/v1/responses).
- Resume-safe by default: if
translations.jsonl already contains some ids, they are skipped.
scripts/epub-translate apply ...:
- Applies translated fragments back into the unpacked XHTML files.
- Updates
dc:language in the OPF and xml:lang in the XHTML.
- Repackages as a valid EPUB (writes
mimetype first, stored/uncompressed).
scripts/epub-translate validate ...: checks basic EPUB container invariants.
JSONL formats
units.jsonl (input to translation) has one JSON object per line, e.g.:
{"id":1,"kind":"xhtml-fragment","doc_path":"EPUB/chapter1.xhtml","xpath":"/html[1]/body[1]/p[3]","tag":"p","source_inner_html":"Hello <em>world</em>!","source_markup_hash":"..."}
translations.jsonl (output from translation) must contain:
{"id":1,"translated_inner_html":"Hola <em>mundo</em>!"}
Translation rules (markup-safe)
- Translate only human-readable text, not markup.
- Do not change any tags, nesting, attribute names, attribute values, URLs, IDs, or filenames.
- Keep entities/character references as-is (e.g.
&,  ).
- If a fragment contains non-translatable text (code, formulas, URLs), leave it unchanged.
Local data and env
- Store all mutable state under /.skills-data//.
- Keep config and registries in .skills-data// (for example: config.json, .json).
- Use .skills-data//.env for SKILL_ROOT, SKILL_DATA_DIR, and any per-skill env keys.
- Install local tools into .skills-data//bin and prepend it to PATH when needed.
- Install dependencies under .skills-data//venv:
- Python: .skills-data//venv/python
- Node: .skills-data//venv/node_modules
- Go: .skills-data//venv/go (modcache, gocache)
- PHP: .skills-data//venv/php (cache, vendor)
- Write logs/cache/tmp under .skills-data//logs, .skills-data//cache, .skills-data//tmp.
- Keep automation in /scripts and read SKILL_DATA_DIR (default to /.skills-data//).
- Do not write outside and /.skills-data// unless the user requests it.
OpenAI config keys
Stored in .skills-data/epub-translate/.env (created by scripts/epub-translate setup):
OPENAI_API_KEYOPENAI_MODEL (default: gpt-5-mini; change via setup --model ..., editing .env, or translate --model ...)OPENAI_BASE_URL (default: https://api.openai.com/v1)OPENAI_REASONING_EFFORT (default: low; change via setup --reasoning-effort ... or editing .env)
1---2name: epub-translate3description: Translate EPUB (.epub) ebooks to another language by unpacking the EPUB container, extracting XHTML block-level fragments into JSONL translation units, translating them via the OpenAI Responses API (e.g. gpt-5.1 / gpt-5-mini) while preserving markup, updating language metadata, and repackaging a valid EPUB (mimetype-first and uncompressed). Use when Codex needs to translate and rebuild EPUB files.4---56# EPUB Translate78## Workflow91. One-time setup (writes `.skills-data/epub-translate/.env`): `scripts/epub-translate setup`102. Extract translation units: `scripts/epub-translate extract --epub /path/book.epub`113. Translate via OpenAI API: `scripts/epub-translate translate --job-dir <job-dir> --target-lang <bcp47> [--fraction 0.1]`124. Apply + repack: `scripts/epub-translate apply --job-dir <job-dir> --translations <job-dir>/translations.jsonl --target-lang <bcp47> --out-epub /path/book.<bcp47>.epub`135. Optional: validate output: `scripts/epub-translate validate --epub /path/book.<bcp47>.epub`1415## Commands16- `scripts/epub-translate setup`:17 - Prompts for `OPENAI_API_KEY` (saved to `.skills-data/epub-translate/.env`).18 - Prompts for default `OPENAI_MODEL` (e.g. `gpt-5.1`, `gpt-5-mini`).19- `scripts/epub-translate extract ...`:20 - Unzips the EPUB into a per-run job dir under `.skills-data/epub-translate/tmp/`.21 - Parses `META-INF/container.xml` → package document (`.opf`) → manifest/spine.22 - Extracts XHTML `<head><title>` and leaf block-level XHTML fragments (inner HTML) in reading order into `units.jsonl`.23 - Optional: include OPF `dc:title` via `--include-opf-title`.24- `scripts/epub-translate translate ...`:25 - Reads `<job-dir>/units.jsonl` and writes `<job-dir>/translations.jsonl`.26 - Uses the OpenAI Responses API (`https://api.openai.com/v1/responses`).27 - Resume-safe by default: if `translations.jsonl` already contains some ids, they are skipped.28- `scripts/epub-translate apply ...`:29 - Applies translated fragments back into the unpacked XHTML files.30 - Updates `dc:language` in the OPF and `xml:lang` in the XHTML.31 - Repackages as a valid EPUB (writes `mimetype` first, stored/uncompressed).32- `scripts/epub-translate validate ...`: checks basic EPUB container invariants.3334## JSONL formats35`units.jsonl` (input to translation) has one JSON object per line, e.g.:36```json37{"id":1,"kind":"xhtml-fragment","doc_path":"EPUB/chapter1.xhtml","xpath":"/html[1]/body[1]/p[3]","tag":"p","source_inner_html":"Hello <em>world</em>!","source_markup_hash":"..."}38```3940`translations.jsonl` (output from translation) must contain:41```json42{"id":1,"translated_inner_html":"Hola <em>mundo</em>!"}43```4445## Translation rules (markup-safe)46- Translate only human-readable text, not markup.47- Do not change any tags, nesting, attribute names, attribute values, URLs, IDs, or filenames.48- Keep entities/character references as-is (e.g. `&`, ` `).49- If a fragment contains non-translatable text (code, formulas, URLs), leave it unchanged.5051## Local data and env52- Store all mutable state under <project_root>/.skills-data/<skill-name>/.53- Keep config and registries in .skills-data/<skill-name>/ (for example: config.json, <feature>.json).54- Use .skills-data/<skill-name>/.env for SKILL_ROOT, SKILL_DATA_DIR, and any per-skill env keys.55- Install local tools into .skills-data/<skill-name>/bin and prepend it to PATH when needed.56- Install dependencies under .skills-data/<skill-name>/venv:57 - Python: .skills-data/<skill-name>/venv/python58 - Node: .skills-data/<skill-name>/venv/node_modules59 - Go: .skills-data/<skill-name>/venv/go (modcache, gocache)60 - PHP: .skills-data/<skill-name>/venv/php (cache, vendor)61- Write logs/cache/tmp under .skills-data/<skill-name>/logs, .skills-data/<skill-name>/cache, .skills-data/<skill-name>/tmp.62- Keep automation in <skill-root>/scripts and read SKILL_DATA_DIR (default to <project_root>/.skills-data/<skill-name>/).63- Do not write outside <skill-root> and <project_root>/.skills-data/<skill-name>/ unless the user requests it.6465### OpenAI config keys66Stored in `.skills-data/epub-translate/.env` (created by `scripts/epub-translate setup`):67- `OPENAI_API_KEY`68- `OPENAI_MODEL` (default: `gpt-5-mini`; change via `setup --model ...`, editing `.env`, or `translate --model ...`)69- `OPENAI_BASE_URL` (default: `https://api.openai.com/v1`)70- `OPENAI_REASONING_EFFORT` (default: `low`; change via `setup --reasoning-effort ...` or editing `.env`)
eugenepyvovarov