--- name: epub-translator description: Translate EPUB books into natural prose in a new target-language edition, preserving reading order, links, and translation continuity, with image-text editing when needed. --- # EPUB Translator Codex owns language, voice, terminology, and edition choices. The bundled helper extracts reading-flow IR and chunks, stores image job results, and builds a new EPUB; it never writes translations. ## Translation Contract - Use the requested target language, defaulting to the user's language. - Translate prose, metadata, and glossary content directly as the main agent in numeric chunk order. Do not delegate text translation or use external machine translation for drafts, terminology, or validation. - Preserve plot, speaker intent, emotional tone, and relationships. Adapt syntax, idioms, punctuation, and dialogue to natural target-language prose while maintaining character voice. - Do not add plot, explanations, censorship, summaries, or translator footnotes. - Preserve reading order, anchors, link destinations, and source image payloads except for explicitly edited image jobs. Source layout wrappers and ruby/furigana are flattened; the helper constructs target XHTML and CSS. - Write the new EPUB to a path distinct from the source. Set `SKILL_DIR` to this skill's absolute directory. From the session project root, use `.codex-skills/epub-translator//` for working files unless the user chooses another workspace. Choose a unique ID for a new translation and pass the same folder as `--workdir` throughout. Resume existing translations at their original paths, including older locations. Keep the final EPUB at the requested output destination. When creating the default workspace in a Git project, ensure `/.codex-skills/` is ignored unless the user intends to version that data. Read [references/translation-data.md](references/translation-data.md) before writing edition settings or translation JSON; consult it again only when its contract is missing from context. ## Start or Resume For a new book: ```bash uv run --script "$SKILL_DIR/scripts/epub_translate.py" inspect --epub --json uv run --script "$SKILL_DIR/scripts/epub_translate.py" ingest --epub --workdir ``` `ingest` requires an empty workdir and refuses to overwrite an existing run. For an existing run, reuse its extracted flow and chunks: ```bash uv run --script "$SKILL_DIR/scripts/epub_translate.py" status --workdir ``` Use `status` and `translation-notes.md` to resume. `valid`, `text_complete`, and `build_ready` describe different states; inspect `errors` and `build_blockers`, not just the exit code. For a flow-v2/chunk-v3 run with omitted source, follow the explicit `recover` procedure in [translation-data.md](references/translation-data.md); preserve completed rows. Fix actual run-data errors at their owning files; routine edition choices do not require rewriting the helper. ## Work Through the Book 1. Read early prose and relevant flow context, then set edition-v2 language tags, page progression, and text direction explicitly in `edition.json`. Keep prose and glossary notes out of this configuration. 2. Before each chunk, read `status`, its seam tail, and `translation-notes.md`. Read nearby flow context when block boundaries, headings, or links affect interpretation. 3. Write one translation per input item, preserving every ID. New flow-v3/chunk-v4 prose items contain whole paragraphs or reading units with protected markers for emphasis, links, images, and other retained content. Preserve paired and atomic marker syntax and nesting while translating the surrounding prose. Do not re-split items, rewrite source chunks or marker metadata, or create intermediate conversion scripts. 4. Re-read the target prose for natural dialogue, consistent voice, scene mood, and typography before accepting the chunk. 5. Keep `translation-notes.md` compact: a rolling narrative summary and reusable name, term, honorific, and style decisions. Preserve unresolved context without inventing book-level facts. 6. Inspect `image-jobs.json`. When it contains editable raster jobs, read [references/image-jobs.md](references/image-jobs.md) and resolve each through main-agent visual triage and a dedicated image subagent when editing is needed. Do not use OCR or bulk image-text extraction. 7. Build when `build_ready` is true, then validate the published artifact against the current run. Peripheral metadata and image attributes should read as concise labels or descriptions; narrative chunks should retain literary voice. Judge the actual content instead of treating chunk size as a quality target. ## Build and Finish ```bash uv run --script "$SKILL_DIR/scripts/epub_translate.py" build --workdir --output uv run --script "$SKILL_DIR/scripts/epub_translate.py" validate --workdir --output ``` Review `build-report.json`, including `untranslated_candidates` and `divergences`. Proper names and context-sensitive translations may be valid; resolve findings through source review. Mechanical validation does not prove translation quality. The helper rebuilds horizontal target XHTML, CSS, and navigation while retaining source reading order, auxiliary spine status, resource locations, and protected content. It checks the final ZIP's package graph and selected payloads before atomically replacing the output. SVG and opaque media are preserved and reported when their text is outside the raster-editing workflow; do not claim that text was translated. If interrupted, retain real completed rows and notes, then resume from `status`; never fabricate missing translations. A blocked image job remains unresolved even if text work can continue. Preserve translation state and notes for further work; after validation, remove only disposable build intermediates from this run. Report the output EPUB and run folder, item and chunk progress, image-job results and unsupported count, reviewed report findings, and build/validation results. Claim completion only when every translation exists, every editable image job is resolved, and both commands succeed.