📚 Bilingual EPUB Translator (English → English/Vietnamese)
Translate any English .epub book into a beautifully formatted bilingual English-Vietnamese edition. The LLM runs directly in Python via HuggingFace Transformers — no Ollama or external server needed.
The model downloads once from HuggingFace Hub and is cached at ~/.cache/huggingface for all future runs.
Prerequisites
- Python 3.10+ (conda env recommended)
- 256 GB RAM (for qwen2.5:72b in INT8 quantization)
Installation
conda activate env03
cd /home/x79/book_translator
pip install -r requirements.txt
Note: The first run will download the model weights (~72 GB for INT8). This is a one-time download cached at
~/.cache/huggingface.
Usage
Basic (uses defaults)
python translate_epub.py "Mona___s_Eyes___40_Thomas_Schlesser__Hildegarde_Serle___40_translator__41___41_.epub"
This produces Mona___s_Eyes_..._bilingual.epub in the same directory.
Specify output path
python translate_epub.py input.epub -o my_bilingual_book.epub
Use a different / smaller model
# Smaller model for faster inference
python translate_epub.py input.epub --model Qwen/Qwen2.5-7B-Instruct
# Another model entirely
python translate_epub.py input.epub --model meta-llama/Llama-3-8B-Instruct
Disable INT8 quantization (uses more RAM)
python translate_epub.py input.epub --no-8bit
All Options
| Flag | Default | Description |
|---|---|---|
input |
(required) | Path to the English .epub file |
-o, --output |
<input>_bilingual.epub |
Output file path |
--model |
Qwen/Qwen2.5-72B-Instruct |
HuggingFace model ID |
--chunk-size |
5 |
Paragraphs per inference call |
--max-new-tokens |
8192 |
Max generated tokens per chunk |
--no-8bit |
off | Disable INT8 quantization |
--no-resume |
off | Ignore cached progress, re-translate all |
--clear-cache |
— | Delete cached checkpoints and exit |
Checkpoint / Resume
Since CPU inference on a 72B model can take many hours, the script saves each chapter's translated HTML to a .bilingual_cache_* directory next to your input file.
If the script crashes or you Ctrl+C:
# Just re-run the same command — it picks up where it left off
python translate_epub.py input.epub
To force a fresh start:
python translate_epub.py input.epub --no-resume
# or delete the cache entirely:
python translate_epub.py input.epub --clear-cache
Output Format
The bilingual EPUB contains, for every paragraph:
- English (bold) — the original text
- Vietnamese (italic, red left border) — the translation
- A Vocabulary Box at the end of each chunk with 3–5 difficult words explained
Troubleshooting
| Problem | Solution |
|---|---|
| Out of memory | Use a smaller model: --model Qwen/Qwen2.5-7B-Instruct |
| Slow inference | Reduce chunk size: --chunk-size 3 |
| Model download fails | Check disk space at ~/.cache/huggingface and internet |
| Poor translation | Try --no-8bit for full precision (needs more RAM) |