book_translator/README.md

📚 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:

1. English (bold) — the original text
2. Vietnamese (italic, red left border) — the translation
3. 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)