# Parsing and Rebuilding EPUB Files in Python: Lessons Learned

> Source: <https://dev.to/jacob_gong/parsing-and-rebuilding-epub-files-in-python-lessons-learned-5e6h>
> Published: 2026-06-27 03:00:46+00:00

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

At [LectuLibre](https://lectulibre.com), 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.

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:

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.

`ebooklib`

with a Dose of Defensive Coding
We evaluated several Python libraries:

`epub`

(pypub)`lxml`

+ manual zip`ebooklib`

We went with [ ebooklib](https://github.com/aerkalov/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.

``` php
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.

``` python
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")
```

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.

``` python
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).

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.

``` python
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.

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.

``` python
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.

``` python
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.

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

``` python
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.

**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.

**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.

**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.

**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.

`ebooklib`

is great but fragileWe’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!*