agentleFS
ai3027ai3027/skills/epub-translate/SKILL.md

epub-translate

Skill1 starsChanged 4 months agoMITView on GitHub

Translate the prose of an English EPUB ebook (especially O'Reilly / technical books) into Chinese while preserving all HTML structure, code, images, links, and indexing. Use whenever the user wants to translate an EPUB, translate an English ebook to Chinese, localize a technical book, or mentions epub/html book translation. Covers the full pipeline — unpack, extract translatable text, translate, backfill, validate, and repackage.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. eugenepyvovarov/mcpbundler-agent-skills-marketplace★ 12same name
    2. fcy3859/skills★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 8 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before translating, ask (use AskUserQuestion):

    line 83
  2. Distinctive:

    Terminology: keep core terms in English (RAG, LLM, CoT), or translate all?

    line 85
  3. Distinctive:

    Index: keep the back-of-book index in English (common for translated technical books since entries key to the English source).

    line 88
  4. Very specific:

    Write zh_<label>.json: a dict mapping id → translated inner_en.

    line 129
  5. Distinctive:

    If it reports PH MISMATCH or TAG MISMATCH, fix those specific records (the script prints which id and what's missing) and rerun.

    line 156
  6. Distinctive:

    After packaging, verify the new EPUB:

    line 178
  7. Very specific:

    Proper nouns: keep English (GPT, Gemini, Claude, Llama, company names, author names, library names like LangChain/Pydantic/LlamaIndex).

    line 191
  8. Distinctive:

    Code/output: never translate. Keep English verbatim — including model responses shown as examples (readers need to see real outputs).

    line 193
  9. Distinctive:

    Figures: only captions translate; in-image text stays English (that's a bitmap.

    line 195
  10. Very specific:

    All scripts are dependency-free (Python 3 stdlib only: re, json, zipfile, xml.etree.ElementTree for structure discovery only — never for …

    line 206
  11. Distinctive:

    Read the JSON records directly (via a small python print) when in doubt.

    line 220

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

EPUB Translation (English → Chinese)

This skill translates the prose of an EPUB ebook into Chinese while leaving code, images, URLs, index markers, and HTML structure untouched. It is built around a placeholder-based extraction/replacement pipeline that guarantees the repackaged EPUB is structurally identical to the original (only text nodes change). It was validated on an O'Reilly book (Generative AI Design Patterns, ~138k words, 32 patterns) and reuses those battle-tested scripts.

When to use

  • User has an .epub (typically English technical book) and wants it in Chinese.
  • User says "翻译这本书" / "translate this epub" / "localize this book".
  • The book is XHTML-based (most are). Works best on O'Reilly / Manning / structured technical EPUBs, but the pipeline is generic.

Core principle: never serialize HTML yourself

The single most important rule: do not parse-and-reserialize the HTML to do translation. Reserialization (via lxml/BeautifulSoup .tostring(), ElementTree, etc.) silently changes quotes, self-closing tags, entity casing, whitespace, and namespaces — corrupting the EPUB. Instead, the pipeline operates at the raw-byte level:

  1. Extract translatable blocks and record their exact byte span in the source.
  2. Replace non-translatable child elements (inline <code>, indexterms, links, MathML) with placeholders like 〔X1〕 / 〔LA1〕…〔LB1〕.
  3. Translate the resulting pure-text strings (keeping placeholders).
  4. Backfill by doing exact substring replacement of each block, expanding placeholders back to their original bytes. Tags/attributes/whitespace are never touched.

A round-trip identity self-test (translate English back to English → must equal the original file byte-for-byte) catches any pipeline bug before you start.

Pipeline overview

.epub ──unzip──► extract_root/
                    │
            extract.py (per html file)
                    │
            strings_<label>.json   (records: id, tag, src_full, inner_en, mapping)
                    │
            [model translates inner_en → zh, keeping placeholders & inline tags]
                    │
            zh_<label>.json
                    │
            validate.py  ──►  <label>.zh.html   (apply.py backfills)
                    │
            package.py  ──►  out.epub

Scripts live in scripts/ next to this SKILL.md. Run them with python.

Step-by-step

0. Unpack the EPUB

mkdir -p _work/extract && cd _work/extract
unzip -o "../book.epub"
cd ..

An EPUB is a ZIP. mimetype must remain the first entry, stored uncompressed — package.py handles this; just don't rezip manually with zip -r.

1. Inspect structure

Find the content HTML files (usually under OEBPS/ or similar). Identify which files are prose to translate (chapters, preface) vs. to leave alone (index, colophon, copyright, cover, titlepage). Confirm the files are XHTML by checking the XML declaration.

2. Confirm scope & terminology with the user

Before translating, ask (use AskUserQuestion):

  • Scope: whole book, a sample chapter first, or specific chapters?
  • Terminology: keep core terms in English (RAG, LLM, CoT), or translate all? Recommend: abbreviations/proper nouns stay English; pattern/concept names get Chinese + English parenthetical on first occurrence.
  • Index: keep the back-of-book index in English (common for translated technical books since entries key to the English source).
  • Output: a new EPUB file.

3. Extract translatable strings

python <skill_dir>/scripts/extract.py "OEBPS/ch01.html"
# → produces strings_ch01.json (label = basename of the html file)

extract.py walks the HTML, finds "leaf prose" block elements (<p>, <h1>–<h6>, <li>, <dt>, <dd>, <td>, <th>, <caption>, <blockquote>), and for each emits a record:

  • id: <label>::<n>
  • tag: the element tag
  • src_full: exact original block substring (opening tag → closing tag)
  • inner_en: inner HTML with non-translatable children replaced by placeholders
  • mapping: placeholder → raw bytes to restore

Placeholder conventions (the braces 〔〕 are U+3014/U+3015 — they never collide with prose and survive translation):

  • 〔X1〕 — opaque element kept verbatim (indexterm, noteref, <code>, MathML…)
  • 〔LA1〕…〔LB1〕 — paired link open/close; the anchor text between them is translatable, the tag bytes are restored exactly.

Records with <2 letters in inner_en are auto-skipped (pure-placeholder blocks).

4. Self-test reversibility (do this once per book, per chapter)

python <skill_dir>/scripts/apply.py selftest strings_ch01.json
# must print "identity round-trip: OK"

This applies the English inner_en back and checks the result equals the original byte-for-byte. If it fails, the extraction has a bug — fix extract.py before translating. This guard is what makes the whole approach trustworthy.

5. Translate

Write zh_<label>.json: a dict mapping id → translated inner_en. Rules:

  • Keep every placeholder exactly (〔X1〕, 〔LA1〕, 〔LB1〕). Missing or extra placeholders corrupt the backfill. validate.py will catch mismatches.
  • Keep inline tags exactly (<em>, <span class="keep-together">, <strong>, <code>). Count of <...> openings in zh must equal count in en — if you merge two <em> into one or drop one, validate.py flags it.
  • Code blocks, model outputs, English example text, prompts, person/place/brand names: keep English (they're either inside opaque placeholders or you choose to leave the whole record English).
  • Translate prose, headings, figure captions, table headers/cells, callout labels (Note→注意, Tip→提示, Warning→警告).
  • Cross-reference labels: Chapter N → 第 N 章, Figure X-Y → 图 X-Y, Table X-Y → 表 X-Y, Pattern N: → 模式 N:.

Because books are long, translate chapter-by-chapter. For very large chapters a hybrid works well: hand-translate the prose records, and for records that are pure code/example output, fall back to the English original (the build script in the worked example does this).

6. Validate + backfill

python <skill_dir>/scripts/validate.py strings_ch01.json zh_ch01.json
# checks coverage, placeholder parity, tag parity, round-trip identity
# on success → produces ch01.zh.html

If it reports PH MISMATCH or TAG MISMATCH, fix those specific records (the script prints which id and what's missing) and rerun. Common fixes:

  • Restored a dropped 〔Xn〕 placeholder.
  • Split a merged <em>…</em> back into the original count.

7. Package

python <skill_dir>/scripts/package.py \
    _work/extract \
    out.epub \
    _work \
    OEBPS/preface01.html OEBPS/ch01.html OEBPS/ch02.html ...

package.py takes: extract_root, output epub path, dir of .zh.html files, then the list of EPUB-relative html paths to swap. Convention: OEBPS/ch01.html → translated file named ch01.zh.html in the zh dir. mimetype is stored first & uncompressed; everything else DEFLATE.

8. Final structural check

After packaging, verify the new EPUB:

  • mimetype is the first entry, STORED, content application/epub+zip.
  • container.xml points to the OPF; OPF is in the zip.
  • zipfile.testzip() returns None (no corruption).
  • Per translated file: count of <pre>, <code>, <img>, indexterm, href, <figure>, <table> equals the original (only text changed).

Translation style guidance

  • Tone: technical, faithful, readable Chinese. Match the book's register.
  • First-occurrence terms: Chinese + English parenthetical, e.g. 「检索增强生成 (RAG)」, 「思维链 (Chain of Thought)」. Subsequent uses: Chinese only (or English only, per user preference).
  • Proper nouns: keep English (GPT, Gemini, Claude, Llama, company names, author names, library names like LangChain/Pydantic/LlamaIndex).
  • Code/output: never translate. Keep English verbatim — including model responses shown as examples (readers need to see real outputs).
  • Figures: only captions translate; in-image text stays English (that's a bitmap; translating it needs OCR, which the user has declined).
  • Footnotes/references: translate the prose, keep citation markup/IDs.

Files in this skill

  • scripts/extract.py — extract translatable strings → JSON (placeholder-based)
  • scripts/apply.py — backfill translations → HTML; includes selftest mode
  • scripts/validate.py — coverage + placeholder/tag parity + round-trip check
  • scripts/package.py — repackage EPUB with swapped HTML, valid mimetype

All scripts are dependency-free (Python 3 stdlib only: re, json, zipfile, xml.etree.ElementTree for structure discovery only — never for serialization).

Avoid these pitfalls

  • Don't rezip manually — you'll break the mimetype-first/STORED requirement. Use package.py.
  • Don't skip the self-test — it's the only thing guaranteeing byte-exact preservation. Run apply.py selftest on each chapter's JSON before translating.
  • Don't translate inside placeholders — 〔X1〕 is atomic; keep it verbatim.
  • Don't merge or drop inline tags — <em> count must match. If unsure, validate.py will tell you exactly which record is off.
  • Don't trust head/sed on the extraction dump for long chapters — persisted tool output can truncate and cause you to translate the wrong text. Read the JSON records directly (via a small python print) when in doubt.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.