How we handle complex EPUB structures for AI translation without breaking navigation and metadata

At LectuLibre, we built an AI‑powered book translation service. Users upload an EPUB, and our pipeline translates the text using LLMs like Claude and DeepSeek. That sounds straightforward until you have to parse and rebuild a valid EPUB without mangling the table of contents, internal links, or styles.

I’m sharing the real‑world challenge we faced, how we chose our tooling, and the ugly corners we discovered when dealing with real‑world EPUB files.

The Problem: EPUB is a Messy Zip File

An EPUB is essentially a ZIP archive containing XHTML, CSS, images, and an OPF manifest. It’s a well‑defined standard (EPUB 3.2), but in practice publishers produce files that bend the rules: missing container.xml, inline styles that break after translation, and structural quirks that make parsing fragile.

Our translation process needed to:

1. Accept any EPUB the user throws at us.
2. Extract all text content while preserving the exact structure.
3. Send each paragraph to an LLM for translation.
4. Re‑insert the translated text into the original XHTML files.
5. Repackage everything into a new, valid EPUB.

Step 4 is the tricky part: the translated text can be longer or shorter, it may contain characters that need escaping, and the surrounding markup must remain intact.

Our Approach: Use ebooklib with a Dose of Defensive Coding

We evaluated several Python libraries:

• epub (pypub) – too simple, no editing support.
• lxml + manual zip – too much boilerplate.
• ebooklib – full read/write with a clean API.

We went with ebooklib. It provides an object‑oriented model of the EPUB structure, allows us to iterate over documents, and can write a new EPUB from the modified objects. The downside: its documentation is sparse and it can choke on malformed files. We had to layer on a lot of validation.

Step 1: Loading and Validating the EPUB

import ebooklib
from ebooklib import epub

def load_epub(epub_path: str) -> epub.EpubBook:
    book = epub.read_epub(epub_path, {"ignore_ncx": True})
    # Force title to be a string (some books have list titles)
    if isinstance(book.title, list):
        book.title = " ".join(book.title)
    return book

But we quickly learned that read_epub can fail silently if the book’s metadata is corrupted. We added a custom validation step that checks for a valid OPF and at least one spine item.

def validate_epub(book: epub.EpubBook):
    if not book.opf:
        raise ValueError("Missing OPF metadata")
    if len(list(book.spine)) == 0:
        raise ValueError("No spine items found – EPUB is unreadable")

Step 2: Extracting Readable Text from XHTML Documents

An EPUB’s content is stored in epub.EpubHtml objects. We iterate over all items in reading order (spine) and parse the body content with BeautifulSoup (lxml parser) because ebooklib’s own get_body_content() returns raw bytes, and we need to extract text paragraph‑by‑paragraph while keeping the HTML structure.

from bs4 import BeautifulSoup
import html

def extract_paragraphs(item: epub.EpubHtml) -> list[dict]:
    soup = BeautifulSoup(item.get_body_content(), "html.parser")
    paragraphs = []
    for tag in soup.find_all(["p", "h1", "h2", "h3", "h4", "h5", "h6", "li"]):
        clean_text = tag.get_text(strip=True)
        if clean_text:
            paragraphs.append({
                "tag": tag,
                "original": clean_text,
                "translated": None
            })
    return paragraphs

We keep a reference to the original BeautifulSoup tag object so we can later replace its text. This is memory‑heavy for large books but works for books under 10 MB (our VPS limit).

Step 3: Translating with an LLM (and Controlling Length)

For each paragraph we call our translation API (Claude or DeepSeek). The tricky part is that some paragraphs are very short (headers) or contain entity references. We escape HTML entities before sending, and decode them afterward.

import requests

def translate_text(text: str, source_lang: str, target_lang: str) -> str:
    escaped = html.escape(text, quote=False)
    response = requests.post(
        "https://api.lectulibre.com/v1/translate",  # simplified
        json={"text": escaped, "source": source_lang, "target": target_lang},
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    translated = response.json()["translated"]
    return html.unescape(translated)

We found that LLMs can sometimes add extra spaces or punctuation. We apply a light post‑processing: trim, normalize spaces, and ensure the translated text doesn’t break the containing tag’s structure.

Step 4: Rebuilding the XHTML with Translated Text

Back in the extract_paragraphs output, we replace the tag.string with the translated text. Since tag.string might be a NavigableString containing child elements, we must be careful. If the tag contains only a string, we replace it. If it contains mixed content, we replace the first text node only, which is a simplification that works for most books.

def replace_text(tag, new_text: str):
    if tag.string is not None and not tag.find_all(text=False):
        # Simple case: tag has only a single text node
        tag.string.replace_with(new_text)
    else:
        # Find the first text node and replace it
        for child in tag.children:
            if isinstance(child, str) and child.strip():
                child.replace_with(new_text)
                break

After all replacements, we set the item’s body content back to the modified HTML.

def update_item(item: epub.EpubHtml, paragraphs: list[dict]):
    for p in paragraphs:
        if p["translated"]:
            replace_text(p["tag"], p["translated"])
    # Rebuild the HTML
    html_str = p["tag"].prettify()  # or extract the full soup
    item.set_body_content(html_str.encode("utf-8"))

A problem here: set_body_content expects bytes, and we must ensure the encoding is UTF‑8. Also, if the original file had a XML declaration or namespaces, we might lose them. We handle that by preserving the item.media_type and other metadata.

Step 5: Writing the Translated EPUB

Once all items are updated, we write the book to a new file. We also add a modified‑date and update the language metadata.

def save_book(book: epub.EpubBook, output_path: str):
    book.set_identifier("urn:uuid:" + str(uuid.uuid4()))
    book.add_metadata("DC", "language", "fr")  # target language
    epub.write_epub(output_path, book, {})

We learned the hard way that epub.write_epub may fail if items reference resources (images, fonts) that aren’t properly registered in the manifest. We iterate all items from the original book and add them to the manifest early to avoid missing dependency errors.

Real‑World Pitfalls and How We Solved Them

1. Broken Table of Contents: After translation, the NCX/NAV files pointed to old file names or anchors that no longer existed because we had renamed items. We now never rename items; we only modify their content in-place. If we must add new items (e.g., for footnotes), we update the TOC manually using ebooklib.epub.Link objects.

2. Inline CSS Overwrites: Some books use inline styles like font-size: 12pt. When a translated paragraph becomes longer, it can overflow fixed‑height containers. We don’t modify CSS, but we added a warning for books with rigid styling and offer a “clean” version without fixed heights.

3. Performance: For a 500‑page novel, the entire pipeline (parse, translate, rebuild) takes about 90 seconds on our VPS (4 vCPU, 8 GB RAM). The LLM calls dominate; we batch paragraphs of up to 5 together to reduce API overhead, trading off a slight translation quality dip.

4. Memory: Loading the entire EPUB and keeping BeautifulSoup trees in memory can spike to 300 MB for large books. We process one book at a time and use a queue to avoid concurrency issues.

Lessons Learned

• ebooklib is great but fragile – always validate the EPUB structure yourself; don’t assume all fields are present.
• Preserve the original item order and names – renaming breaks internal links.
• Escape/unescape HTML entities when moving text between HTML and plain text.
• Translation quality depends on context – we’re experimenting with sending the entire chapter instead of individual paragraphs, but that increases latency.

What’s Next?

We’re exploring pandoc for pre‑conversion to a simpler intermediate format that’s easier to manipulate. However, the rebuild step becomes more complex. For now, ebooklib + BeautifulSoup serves our needs.

If you’re building an EPUB processing tool in Python, I hope these real‑world insights save you some of the debugging hours we spent. Got a better approach? I’d love to hear it in the comments!

Happy coding!