Anmelden
eugenepyvovarov

epub-translate

by @eugenepyvovarov in AI & LLM
5
1
# Install this skill:
npx skills add eugenepyvovarov/mcpbundler-agent-skills-marketplace --skill "epub-translate"

Install specific skill from multi-skill repository

# Description

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.

# SKILL.md

name: epub-translate
description: 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.

EPUB Translate

Workflow

  1. One-time setup (writes .skills-data/epub-translate/.env): scripts/epub-translate setup
  2. Extract translation units: scripts/epub-translate extract --epub /path/book.epub
  3. Translate via OpenAI API: scripts/epub-translate translate --job-dir <job-dir> --target-lang <bcp47> [--fraction 0.1]
  4. Apply + repack: scripts/epub-translate apply --job-dir <job-dir> --translations <job-dir>/translations.jsonl --target-lang <bcp47> --out-epub /path/book.<bcp47>.epub
  5. 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. &amp;, &#160;).
  • 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_KEY
- OPENAI_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)

# Related Skills

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

โšก Amp ๐Ÿš€ Antigravity ๐Ÿค– Claude Code ๐Ÿฆ€ Clawdbot ๐Ÿ“ Codex โ–ถ๏ธ Cursor ๐Ÿค– Droid ๐Ÿ’Ž Gemini CLI ๐Ÿ™ GitHub Copilot ๐Ÿชฟ Goose ๐Ÿ“Š Kilo Code ๐Ÿ”ง Kiro CLI ๐Ÿ’ป OpenCode ๐Ÿฆ˜ Roo Code ๐ŸŒฒ Trae ๐Ÿ„ Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.