Why Building Your Own EPUB Translator Is Harder Than You Think

A tweet recently went viral among developers. @cat88tw shared their attempt to build an EPUB translator using Claude Code and described, in blunt terms, just how much harder it was than expected. The tweet hit 1,671 views -- not because the idea was unusual, but because every developer who's tried the same thing nodded along in recognition.

The pitch sounds simple. EPUBs are just HTML and CSS zipped into a file. Modern AI models can translate text beautifully. So you wire the two together, and you're done in a weekend.

Except you're not. You're done in a weekend only if you're willing to accept broken formatting, garbled chapters, missing images, and translations that fall apart the moment you try to open the file on a Kindle or Kobo. Building a reliable EPUB translator -- one that handles real-world books, not just toy examples -- is a genuine engineering challenge.

Here's why.

Challenge 1: EPUB Structure Is Deceptively Complex

An EPUB file is a ZIP archive containing XHTML files, CSS stylesheets, images, fonts, metadata, and a navigation system. The standard (EPUB 2 and EPUB 3) defines how these pieces fit together, but publishers interpret the standard loosely. Very loosely.

Some books split content into one file per chapter. Others put everything in a single monolithic XHTML file. Some use nested <div> structures for sections. Others use <section> tags, or <article> tags, or no semantic markup at all. The table of contents might be an NCX file (EPUB 2), a Navigation Document (EPUB 3), or both. Some books have inline CSS. Others reference external stylesheets. Some embed fonts. Others rely on the reader's system fonts.

Your translator needs to handle all of these variations correctly. The moment you make assumptions about structure -- "chapters are always separate files" or "CSS is always external" -- you'll encounter a real book that breaks your parser.

The OPF manifest file lists every resource in the book and the reading order. If your translator adds, removes, or renames files without updating the manifest, the EPUB becomes invalid. Most e-reader apps will refuse to open it or display it incorrectly.

Challenge 2: Preserving Formatting While Replacing Text

This is where most DIY projects die. Translating the text is the easy part. Keeping the formatting intact afterward is brutally hard.

Consider a paragraph with mixed formatting:

<p>
  The author notes that <em>this particular finding</em> was
  <strong>statistically significant</strong> (p < 0.001), as shown in
  <a href="chapter3.xhtml#table2">Table 2</a>.
</p>

Your translator needs to:

Extract the translatable text while preserving the HTML tags
Send the text to a translation model
Map the translated text back to the correct tags -- even though the word order, sentence structure, and text length have completely changed
Preserve the hyperlink reference, which should not be translated
Handle the HTML entity (<) without corrupting it

Now multiply this by every formatting pattern in the book: footnotes, superscripts, ruby text annotations, drop caps, pull quotes, epigraphs, poetry with line breaks, mathematical notation, and tables with merged cells. Each one is a special case that your mapping logic needs to handle.

If you naively send the raw HTML to a language model and ask it to translate, the model will frequently mangle the tags, change attribute values, drop closing tags, or rewrite the markup structure entirely. If you strip the HTML first and translate plain text, you lose all formatting and have no way to put it back.

Challenge 3: Chapter Splitting and Context Windows

A typical book contains 60,000 to 100,000 words. No current language model can process an entire book in a single API call and return a coherent translation. You have to split the book into chunks.

But splitting introduces its own problems:

Context loss: A sentence at the end of one chunk might reference something introduced at the beginning of the next. Character names, technical terms, and pronouns need consistent translation across chunk boundaries.
Split points matter: If you split in the middle of a paragraph, a list, or a table, you'll get broken HTML. If you split between paragraphs, you still risk losing context.
Terminology consistency: The same word might be translated differently in different chunks if each chunk is processed independently. A character named "Light" in a Japanese novel might become "Light" in one chapter and "Hikari" in another.

Professional translation tools maintain glossaries and context windows that overlap between chunks. Building this correctly requires careful engineering -- not just splitting on paragraph boundaries and hoping for the best.

Challenge 4: CSS and Font Handling

Translating text changes its length. A 20-word English sentence might become 35 words in German or 12 characters in Chinese. This has cascading effects on layout:

Fixed-width containers overflow or leave awkward whitespace
CSS columns break when content length changes dramatically
Vertical text layouts (common in Japanese books) need entirely different CSS rules than horizontal layouts
Custom fonts may not include glyphs for your target language. A book set in a Latin-only typeface will show empty boxes or fallback fonts when translated to Chinese or Arabic
Line height and spacing optimized for one script look wrong for another. CJK characters need more line height than Latin text. Arabic script needs different baseline alignment.

Your translator either needs to adjust CSS properties for the target language or accept that the output will look broken. Neither option is trivial.

Challenge 5: CJK and RTL Scripts

If your translator only handles European languages, you might get away with ignoring script-specific issues. The moment you add Chinese, Japanese, Korean, or Arabic support, the complexity doubles.

CJK challenges:

Word segmentation -- Chinese and Japanese don't use spaces between words, so your chunking logic can't rely on whitespace
Ruby text (furigana) -- pronunciation guides above kanji need to be preserved or regenerated for the translated text
Punctuation rules differ -- Chinese uses full-width punctuation, Japanese has specific rules for line-breaking
Vertical writing mode is standard in many Japanese and traditional Chinese books

RTL challenges:

Arabic and Hebrew text flows right-to-left, which affects not just the text but the entire page layout
Bidirectional text (mixing English and Arabic in the same paragraph) requires correct Unicode BiDi algorithm handling
Arabic script is cursive -- letters change shape based on their position in a word. If your HTML processing breaks a word across tags incorrectly, the rendering breaks

Most developers discover these issues only after a user tries to translate a book to or from one of these languages and reports that the output is unreadable.

Challenge 6: EPUB Validation and Reader Compatibility

Generating a valid EPUB that looks correct on every reader app is surprisingly difficult. E-readers are not web browsers -- they each implement a subset of the EPUB standard with their own quirks.

Apple Books renders EPUB 3 features that Kindle ignores
Kobo handles CSS differently than Google Play Books
Older Kindle devices require MOBI conversion and have strict formatting limits
Some readers crash on malformed XHTML, while others try to fix it silently

After translation, your output needs to pass EPUB validation (epubcheck) and render correctly on at least the major platforms. Testing across readers is time-consuming and reveals platform-specific bugs that are tedious to fix.

Challenge 7: Error Handling at Scale

A book is not a single API call. Translating a 300-page book might require 200+ API calls to a language model. Each call can fail -- rate limits, timeouts, malformed responses, content filters, or simply a bad translation.

Your translator needs:

Retry logic with exponential backoff
Progress tracking so you can resume from where you left off
Output validation to catch garbled HTML before packaging the final EPUB
Cost estimation so users know what they'll pay before starting

Building reliable infrastructure for hundreds of sequential API calls, with error handling and resumption, is a significant engineering effort on its own.

Why a Purpose-Built Tool Makes Sense

Every challenge above is solvable. But solving all of them together -- and keeping them solved as EPUB standards evolve, language models change their APIs, and new edge cases appear -- is a full-time job.

This is exactly why EPUBTranslator exists. Instead of spending weeks building and debugging your own pipeline, you upload a file, pick a language, and get back a properly formatted EPUB. The tool handles all the complexity described above: structure parsing, format preservation, chunk management, CSS adjustment, CJK and RTL support, validation, and error recovery.

For developers who enjoy the challenge, building an EPUB translator is a great learning project. You'll gain deep knowledge of the EPUB format, HTML/CSS edge cases, and the practical limits of language model APIs. But if your goal is actually reading a book in another language -- not spending a month debugging edge cases in XHTML parsing -- a purpose-built tool will save you a significant amount of time and frustration.

The developer behind that viral tweet learned this the hard way. You don't have to.

Conclusion

Building an EPUB translator looks simple on the surface: parse some HTML, call a translation API, zip it back up. But the gap between a working prototype and a tool that handles real books reliably is enormous. EPUB structure variation, formatting preservation, context management, script-specific rendering, cross-reader compatibility, and production error handling each add layers of complexity that compound on each other.

If you're a developer who wants to understand these challenges deeply, by all means build one. You'll learn a lot. But if you just want to read a great book that happens to be in another language, use a tool that's already solved these problems. EPUBTranslator handles the hard parts so you can focus on what matters -- actually reading the book.