TEPUB - Tools for EPUB

Transform EPUB books into translations, audiobooks, and web pages – automatically.

TEPUB is a comprehensive toolkit for processing EPUB files. Translate books into any language, create professional audiobooks with natural voices, export to markdown, or publish as interactive websites.

Features

📖 Translation

• Multi-language support: Translate to/from any language
• Local by default: translates on your own computer with Ollama and TranslateGemma; OpenAI, Anthropic Claude, Google Gemini, xAI Grok and DeepL are supported too
• Dual output modes:
  • Bilingual: Original and translation side-by-side (perfect for learning)
  • Translation-only: Professional translated edition
• Smart processing: Auto-skip front/back matter, parallel translation, resume capability
• Glossary: one rendering per term across the whole book, proposed from the book's index and names, checked on every reply

🎧 Audiobook Creation

• Dual TTS providers:
  • Edge TTS (Free): 57+ voices in multiple languages, no API key required
  • OpenAI TTS (Premium): 6 high-quality voices with superior naturalness
• Professional output: M4A format with chapter markers and embedded cover art
• Chapter management: Export, edit, and update chapter titles and timestamps
• Flexible control: Adjustable speed, voice selection, resume support
• Cost: Free with Edge TTS, or ~$11-22 per 300-page book with OpenAI TTS

📱 Export Formats

• Web: Interactive HTML viewer with live translation toggle
• Markdown: Plain text with preserved formatting and images
• EPUB: Bilingual or translation-only editions

Quick Start

Installation

Automatic (Mac/Linux)

git clone https://github.com/xiaolai/tepub.git
cd tepub
./install.sh
source .venv/bin/activate

Manual (All platforms)

git clone https://github.com/xiaolai/tepub.git
cd tepub
python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e .[dev]

See INSTALL.md for detailed platform-specific instructions.

Translation Setup

By default TEPUB translates on your own computer: free, private, and with no API key. It uses Ollama with TranslateGemma 12B, a translation model of 8.1 GB:

# Install Ollama from https://ollama.com, then:
ollama pull translategemma:12b

TEPUB checks before translating that Ollama answers and has the model, and says how to fix it if not. If Ollama runs on another machine, point TEPUB at it in ~/.tepub/config.yaml:

primary_provider:
  name: ollama
  model: translategemma:12b
  base_url: http://other-machine:11434

To use a cloud service instead, set primary_provider and its API key:

primary_provider:
  name: openai        # or anthropic, gemini, grok, deepl
  model: gpt-4o

echo 'OPENAI_API_KEY=sk-your-key-here' > .env

Basic Usage

Translate a book:

tepub extract mybook.epub
tepub translate mybook.epub --to "Simplified Chinese"
tepub export mybook.epub          # writes mybook.zh-CN.bilingual.epub beside the book
tepub status mybook.epub          # where the book stands, and the next step

Create audiobook (Free Edge TTS):

tepub extract mybook.epub
tepub audiobook generate mybook.epub
# Interactive voice selection will appear; in a script, pass --voice

Create audiobook (Premium OpenAI TTS):

tepub audiobook generate mybook.epub --tts-provider openai --voice nova
# Requires OPENAI_API_KEY in environment

All-in-one pipeline:

tepub mybook.epub --to Spanish    # extract, translate and export

Common Tasks

Translation

Translate to different languages:

tepub pipeline book.epub --to "Simplified Chinese"
tepub pipeline book.epub --to Spanish
tepub pipeline book.epub --to French

Choose translation provider: set primary_provider in ~/.tepub/config.yaml (all books) or in the book's config.yaml (one book); see Configuration. For one run: tepub translate book.epub --model qwen3.5:9b, or --provider openai --model gpt-4o. --dry-run shows what a run would translate. tepub config show lists the settings in effect and where each came from.

translate and pipeline exit with 3 when some units failed (--allow-failures exits with 0); run the same command again to retry them.

Reasoning models on Ollama: models that think before answering, such as Qwen 3, can take minutes per paragraph. think: false turns that off:

primary_provider:
  name: ollama
  model: qwen3.5:9b
  think: false

Translation-only output, or both editions:

tepub export book.epub --mode translated      # book.zh-CN.epub
tepub export book.epub --mode both --out ~/Books

Audiobooks

Edge TTS (Free, 57+ voices):

# Interactive voice selection
tepub audiobook generate book.epub

# Specify voice directly
tepub audiobook generate book.epub --voice en-US-GuyNeural    # Male
tepub audiobook generate book.epub --voice en-US-JennyNeural  # Female
tepub audiobook generate book.epub --voice en-GB-RyanNeural   # British

# See all voices
edge-tts --list-voices

OpenAI TTS (Premium, 6 voices):

# Standard quality (tts-1)
tepub audiobook generate book.epub --tts-provider openai --voice nova

# Higher quality (tts-1-hd)
tepub audiobook generate book.epub --tts-provider openai --tts-model tts-1-hd --voice nova

# Adjust speed
tepub audiobook generate book.epub --tts-provider openai --voice nova --tts-speed 1.2

# Available OpenAI voices:
# - alloy: Neutral, balanced
# - echo: Male, authoritative
# - fable: British, expressive
# - onyx: Deep male, professional
# - nova: Female, friendly
# - shimmer: Female, warm

Custom cover image:

tepub audiobook generate book.epub --cover-path ~/Pictures/mycover.jpg

Chapter management:

# Preview chapter structure before generating audiobook
tepub audiobook export-chapters book.epub
# Edit chapters.yaml to customize chapter titles
tepub audiobook generate book.epub  # Uses custom titles from chapters.yaml

# Extract chapters from existing audiobook
tepub audiobook export-chapters audiobook.m4a

# Update audiobook with edited chapter markers
tepub audiobook update-chapters audiobook.m4a chapters.yaml

Export

Create web version:

tepub export book.epub --format web           # book.zh-CN.web.zip

Export to markdown:

tepub extract book.epub --markdown            # into book/markdown/

Configuration

TEPUB uses a two-level configuration system:

Global Config: ~/.tepub/config.yaml

Apply settings to all books:

# Translation
source_language: auto
target_language: Simplified Chinese
translation_workers: 3

primary_provider:
  name: ollama                  # the default; or openai, anthropic, gemini, grok, deepl
  model: translategemma:12b

# Audiobook
audiobook_tts_provider: edge    # or: openai
audiobook_workers: 3

# Skip rules
skip_rules:
  - keyword: index
  - keyword: appendix

Per-Book Config: book/config.yaml

Created automatically when you run tepub extract book.epub. Override global settings:

# Choose TTS provider
audiobook_tts_provider: openai
audiobook_tts_model: tts-1-hd
audiobook_voice: nova

# Or use Edge TTS
audiobook_tts_provider: edge
audiobook_voice: en-US-AriaNeural

# Custom cover
cover_image_path: ~/Pictures/mycover.jpg

# Output mode
output_mode: translated_only

# Skip specific sections
skip_rules:
  - keyword: prologue
  - keyword: epilogue

See config.example.yaml for all available options with detailed explanations.

Output Structure

Translation

mybook.epub                      # Original
mybook.zh-CN.bilingual.epub      # Output: both languages
mybook.zh-CN.epub                # Output: translation only (--mode translated)
mybook.zh-CN.web.zip             # Web viewer (--format web)
mybook.zh-CN.bilingual.web.zip   # Bilingual web viewer (--format web --mode both)
mybook/                          # Workspace
├── config.yaml                  # Per-book settings
├── segments.json                # Extracted content
├── state.json                   # Translation progress
├── exports.json                 # What export wrote, and where
└── markdown/                    # Only with extract --markdown

Audiobooks

mybook/
├── audiobook@edgetts/           # Edge TTS audiobooks
│   ├── mybook.m4b               # Final audiobook
│   └── segments/                # Cached audio segments
└── audiobook@openaitts/         # OpenAI TTS audiobooks
    ├── mybook.m4b
    └── segments/

Provider-specific folders let you create both versions for comparison.

Advanced Features

Resume Interrupted Work

TEPUB automatically saves progress. To resume, run the same command again; tepub status book.epub shows how far a book has got.

tepub translate book.epub --to Spanish
tepub audiobook generate book.epub

Parallel Processing

Speed up translation (uses more API credits):

# In config.yaml
translation_workers: 5    # Default: 3
audiobook_workers: 5      # Default: 3

Glossary: One Rendering per Term

tepub glossary build book.epub      # proposes terms; review, save as book/glossary.yaml
tepub translate book.epub           # holds each paragraph to the glossary
tepub glossary check book.epub      # lists misses; --retranslate redoes them

target_language: Simplified Chinese
terms:
  - source: scam compound     # lowercase: also matches the plural
    target: 诈骗园区
    avoid: [集中营]
  - source: Telegram
    target: Telegram           # same as source: left untranslated

Limits: glossary build proposes terms for English books only, and renderings are checked as written, so languages that inflect (German, Russian) see false misses. Review proposed renderings; the model gets names wrong.

Custom Translation Style

# In config.yaml
prompt_preamble: |
  You are a literary translator specializing in preserving artistic voice.
  {language_instruction}
  {mode_instruction}
  Maintain the author's style, tone, metaphors, and cultural nuances.

Selective File Processing

After extraction, edit book/config.yaml:

# Only translate specific files
translation_files:
  - Text/chapter-001.xhtml
  - Text/chapter-002.xhtml
  # - Text/appendix.xhtml    # Commented = skipped

# Different files for audiobook
audiobook_files:
  - Text/chapter-001.xhtml
  # - Text/copyright.xhtml   # Skip copyright in audiobook

Debug Commands

tepub debug workspace book.epub    # Show workspace info
tepub debug pending                 # What's left to translate
tepub debug show-skip-list          # What was skipped

Cost Estimates

Translation (300-page book)

• Ollama (local, the default): Free; speed depends on your hardware
• OpenAI GPT-4o: ~$0.50-2.00
• Anthropic Claude: ~$0.30-1.50

Audiobook (300-page book, ~750,000 characters)

• Edge TTS: Free
• OpenAI tts-1: ~$11.25
• OpenAI tts-1-hd: ~$22.50

Recommendations

• Free and private (the default): Ollama + Edge TTS
• Best Quality: OpenAI GPT-4 + OpenAI TTS-1-HD (~$25 total)
• Best Value with a cloud service: OpenAI GPT-4 + Edge TTS (~$1.50 total)

Troubleshooting

"Cannot reach Ollama" or "does not have the model"

Ollama is the default translation provider. Start it (ollama serve, or open the Ollama app) and install the model with ollama pull translategemma:12b, or set primary_provider to another service in ~/.tepub/config.yaml.

"API key not found"

# Set environment variable
export OPENAI_API_KEY="sk-your-key-here"

# Or create .env file
echo 'OPENAI_API_KEY=sk-your-key-here' > .env

"ModuleNotFoundError: No module named 'openai'"

pip install -e .[dev]
# Or specifically: pip install openai

Audiobook has no sound

# Install FFmpeg
brew install ffmpeg           # Mac
sudo apt install ffmpeg       # Linux
# Windows: download from ffmpeg.org

Translation fails

# Check status
tepub debug pending

# Reset errors and retry
rm book/state.json
tepub translate book.epub --to Spanish

More solutions: GitHub Issues

Privacy & Security

• Local processing: Books stay on your computer (except API calls)
• No telemetry: TEPUB collects no usage data
• Provider privacy: Translation APIs see text but don't store it long-term
• Maximum privacy: Use Ollama for fully local operation

Requirements

• Python: 3.10 or newer (3.11+ recommended)
• OS: macOS, Linux, or Windows 10+
• Disk: ~500 MB
• RAM: 2-4 GB
• FFmpeg: Required for audiobooks (auto-installed on Mac/Linux)

Support

• Documentation: You're reading it!
• Installation: INSTALL.md
• Changelog: CHANGELOG.md
• Issues: GitHub Issues
• Command help: tepub --help or tepub <command> --help

Credits

Built with:

• lxml - EPUB parsing and writing
• edge-tts - Free text-to-speech
• OpenAI - Translation and premium TTS
• Rich - Beautiful terminal output
• Click - CLI framework
• Pydantic - Configuration validation

License

MIT License - see LICENSE for details.

For Developers

git clone https://github.com/xiaolai/tepub.git
cd tepub
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

pytest
pytest --cov=src --cov-report=html

ruff check src tests
black src tests

src/
├── cli/              # Command-line interface
├── extraction/       # EPUB extraction
├── translation/      # Translation pipeline
├── audiobook/        # TTS and audiobook creation
├── injection/        # Insert translations into EPUB
├── web_export/       # Web viewer generation
├── epub_io/          # EPUB reading/writing
├── config/           # Configuration management
└── state/            # Progress tracking

Made with ❤️ for language learners, audiobook enthusiasts, and book lovers everywhere.

Version 0.2.0 | Changelog | Issues