EPUB Translator - Universal AI-Powered Book Translation

Translate EPUB books between languages using AI code assistants while preserving formatting, structure, and metadata.

Works with: Claude Code, Gemini CLI, Cursor, Codex, GitHub Copilot, and any AI assistant

See It In Action

📺 Live Demo & Screenshots - See what the translation process looks like

🎬 Video Tutorial - 3-minute walkthrough (coming soon)

Want to see real examples? Check out the Baneblade case study showing a complete 300-page book translation.

Features

• ✅ Preserves Structure - HTML/XML tags, CSS styling, and formatting stay intact
• ✅ Maintains Navigation - Chapter structure, TOC, and metadata preserved
• ✅ Smart Translation - Protects proper names and technical terms
• ✅ Glossary Support - Use translation dictionaries for consistency (i18n-style)
• ✅ Community Glossaries - Pre-made dictionaries for popular universes (Warhammer 40k, Harry Potter)
• ✅ Batch Processing - Translate multiple chapters/pages in parallel
• ✅ Universal Compatibility - Works with ANY AI assistant
• ✅ Native Claude Skill - Fully automated for Claude Code users

Quick Start

Option 1: For Claude Code Users (Fully Automated)

1. Clone this repository:

   cd ~/.claude/skills/
   git clone https://github.com/vbalko-claimate/epub-translator.git

2. Translate a book:

   claude "translate this EPUB book from English to Czech: book.epub"

3. 💡 Consider skipping permissions (optional but recommended):

   claude --dangerously-skip-permissions "translate this EPUB book from English to Czech: book.epub"

   Why skip permissions?

   • ✅ Auto-approves all file operations (no manual confirmations)
   • ✅ Much faster workflow (10-50+ chapters = 10-50+ approvals saved)
   • ✅ Automatic validation runs without interruption
   • ⚠️ Trade-off: Less control, but skill is designed to be safe

That's it! Claude will automatically extract, translate, and rebuild your EPUB.

📖 Detailed Installation Guide →

Option 2: For All Other AI Assistants (Manual Workflow)

For EPUB:

1. Extract the EPUB:

   mkdir epub_workspace
   unzip book.epub -d epub_workspace/

2. Use prompt templates from prompts/ directory:

   • Copy each prompt in sequence
   • Paste into your AI assistant (Claude web, Gemini, Cursor, etc.)
   • Follow the step-by-step instructions

3. Rebuild the EPUB:

   cd epub_workspace
   zip -0 -X ../translated.epub mimetype
   zip -r ../translated.epub META-INF OEBPS

PDF Translation (Optional)

If you have a PDF book, you can convert it to EPUB and then translate it:

Prerequisites:

• None! Pure Python (auto-installs ALL dependencies on first run)

Workflow:

# 1. Convert PDF to EPUB
python scripts/convert_pdf_to_epub.py mybook.pdf

# 2. Translate the EPUB (existing workflow)
claude "translate mybook.epub from English to Czech"

Quality expectations:

• Good for: Novels, simple text books, standard layouts
• Acceptable for: Technical books with some tables/diagrams
• Not suitable for: Multi-column papers, scanned PDFs, layout-critical documents

Image handling:

• ✅ Extracts embedded images from PDF
• ✅ Preserves JPEG, PNG, GIF, TIFF formats
• ✅ Automatically embeds images in EPUB
• ⚠️ Images placed at end of each chapter
• ⚠️ Small decorative images (<100x100px) filtered out

Important: PDF→EPUB conversion is lossy (layout changes from fixed to reflowable). If you need to preserve exact PDF formatting, use a dedicated PDF editor instead.

Real-World Example

Book: Baneblade by Guy Haley (Warhammer 40k) Pages: 300+ Chapters: 31 (Prologue, Chapters 1-29, Epilogue) Time: ~2 hours Quality: All proper names preserved, formatting intact, valid EPUB

See full case study →

How It Works

EPUB Translation

EPUB files are ZIP archives containing XHTML files for each chapter. This workflow:

1. Extracts the EPUB to access individual chapter files
2. Translates each chapter while preserving HTML structure
3. Updates metadata (language codes, TOC labels)
4. Rebuilds everything into a valid EPUB

book.epub (ZIP)
├── mimetype
├── META-INF/container.xml
└── OEBPS/
    ├── content.opf (metadata - update language)
    ├── toc.ncx (navigation - translate labels)
    ├── chapter-1.xhtml (translate content)
    ├── chapter-2.xhtml (translate content)
    ├── css/ (preserve untouched)
    └── images/ (preserve untouched)

Learn more about EPUB structure →

Supported Languages

Any language pair! Examples:

• 🇬🇧 English → 🇨🇿 Czech
• 🇫🇷 French → 🇬🇧 English
• 🇪🇸 Spanish → 🇩🇪 German
• 🇯🇵 Japanese → 🇬🇧 English
• And any other combination!

Documentation

• How It Works - Understanding EPUB structure
• Glossary System - 📚 Control translations with dictionaries
• Context Management - ⚠️ Critical: Avoid running out of memory
• Troubleshooting - Common issues and solutions
• Examples - Step-by-step walkthrough sessions

Translation Glossaries

Use pre-made dictionaries for consistent translations:

• 📖 Warhammer 40,000 (en→cs) - Official + community terms
• 📖 Template (template.txt) - Create your own glossary

How glossaries work:

PRESERVE: Cortein           ← Never translate (character name)
TRANSLATE: Mars → Mars      ← Use specific translation
PRESERVE_WITH_GRAMMAR: bolter  ← Keep word, apply Czech cases (bolteru, bolterem)
CONTEXT: Chapter → depends  ← "Kapitola" in headings, "Řád" for military units

Usage:

# Claude Code
claude "translate book.epub using glossary warhammer40k-en-cs.json"

# Manual (any AI)
# Include glossary terms in your translation prompts

Learn more about glossaries →

Tool Comparison

Feature	Claude Skill	Universal Prompts
Automation	Fully automated	Semi-manual
AI Compatibility	Claude Code only	Any AI assistant
Setup Complexity	Install once	Copy-paste prompts
Speed	Fastest (~2 hrs)	Slower (~3-4 hrs)
Best For	Repeat translations	One-time use

Requirements

All users need:

• ZIP/UNZIP utilities (built-in on Mac/Linux, install on Windows)
• An EPUB file to translate
• Access to an AI code assistant

Claude Code users additionally need:

• Claude Code CLI installed
• Skill installed in ~/.claude/skills/epub-translator

Translation Quality Tips

What Gets Preserved ✅

• Proper names: Characters, places, organizations (e.g., "Mars Triumphant" stays as-is)
• Technical terms: Genre-specific terminology (e.g., "Baneblade", "lascannon")
• HTML structure: All tags, CSS classes, image references
• Formatting: Bold, italics, paragraph styles

What Gets Translated 📝

• Narrative text: Dialogue, descriptions, narration
• Chapter titles: "Chapter 1" → "Kapitola 1" (or your target language)
• Metadata: Table of Contents, About the Author sections
• Navigation labels: Prologue → Prolog, Epilogue → Epilog

See translation best practices →

Contributing

Contributions are welcome! Whether it's:

• 🐛 Bug fixes
• ✨ New features
• 📚 Documentation improvements
• 🌍 Prompt templates for new AI assistants

See CONTRIBUTING.md for guidelines.

Roadmap

• Support for more ebook formats (MOBI, AZW3)
• GUI application for non-technical users
• Enhanced translation memory/glossary support
• Batch translation of multiple books

License

MIT License - see LICENSE file for details.

Credits

Created by Vladimir Balko

Inspired by translating "Baneblade" by Guy Haley (Warhammer 40k novel) from English to Czech.

Links

• 📝 Blog Post: How I Translated a 300-Page Book in 2 Hours
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• ⭐ Star this repo if you find it useful!

---

Made with ❤️ for book lovers who can't wait for official translations