Parsing and Rebuilding EPUB Files in Python: Lessons Learned

LectuLibre built an AI-powered book translation service that parses and rebuilds EPUB files without breaking navigation or metadata. The team chose the ebooklib Python library but had to add extensive validation to handle malformed files, including missing container.xml and corrupted metadata. They iterate over spine items, extract paragraphs with BeautifulSoup, translate via Claude or DeepSeek, and replace text while preserving HTML structure.

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