Round-tripping an EPUB through an LLM: the hard part is the ledger, not the translation

Everything in that loop hangs on one identifier. Extraction records the item id, the file name and the parsed soup for each document item ^[9]; the rebuild looks the chapter up again by id, re-serialises the tree and calls `set_content` before writing the book out ^[11]. Using the manifest id rather than the path is the right call, because the OPF manifest lists every file with an id and properties, and any rename or addition obliges you to update it ^[6]. The id is the join key for the whole round trip ^[5].

Provenance inside a chapter is thinner. Extracted text is a list of paragraph strings joined with blank lines ^[9], and reinsertion is positional: the paragraph tags in the original tree are zipped against the translated strings in order ^[10]. Ordinal position is the only thing tying a returned string to its node, which is why a count mismatch raises `ValueError` rather than guessing ^[10]. Failing loudly is right. Worth noting is where in the sequence the failure lands: after the chapter has been through Claude or DeepSeek ^[1], and at chapter granularity rather than paragraph granularity, so there is nothing partial to salvage ^[2].

Then the selector. `find_all('p')` is the only thing that gathers text, and the same call is the only thing that receives it back ^[9][10]. Headings, list items and table cell contents are neither sent to the model nor overwritten, so they emerge from a translation pipeline still in the source language ^[1]. For a book whose section titles carry meaning, the output is bilingual by construction.

Replacement is destructive in a second way. `clear()` empties the paragraph before the translated string is appended ^[10], and it takes the descendants with it: emphasis, inline links and any id attributes on elements nested in that paragraph do not survive ^[3]. So the design preserves everything around the prose, the images and styles and fonts inside the archive ^[2], while flattening the markup within it.

The namespace warning cuts both ways too. The post notes that XHTML documents declare `xmlns` and that `html.parser` can mangle markup when namespaces are not handled ^[5]. That same parser sits on the write path, since new content is `str(soup)` encoded as UTF-8 ^[11], so whatever the read drops the write cannot restore ^[4]. Encoding is a separate irritant the author flags on its own: source books arrive in various encodings, and model output can contain smart quotes and other characters that need handling ^[7].

Which puts the model call in its proper place. It is the cheap and swappable component. The durable asset is the map from every extracted string back to the exact node it must return to, and in this design that map covers paragraphs and nothing else ^[1][5].