Comic Translator

Production-grade comic/manga translation pipeline: bubble detection → OCR → translation → text rendering.

comic-translator page.jpg -o output.png
comic-translator manga_chapter/ --preset manga-jp --export cbz --workers 4

Features

• Bubble detection: OpenCV contour-based and OCR-first flood fill (--detect-method contour|ocr)
• OCR: easyocr with GPU/CPU fallback, confidence filtering
• Translation: Google Translate, OpenAI-compatible LLM, dummy, fallback chains
• Rendering: PIL/Pillow with auto font sizing, white outline, inpainting
• Preprocessing: CLAHE, unsharp mask, denoise, deskew (--preprocess)
• Exports: CBZ (+ComicInfo.xml), PDF, EPUB 3.0 fixed-layout
• Pluggable translators: Google, OpenAI, 9+ LLM providers via --provider
• Presets: built-in (manga-jp, manga-en, webtoon, quick) + user-saved
• Batch: parallel workers, resume, progress state, CSV/XLSX reports, webhooks
• API server: FastAPI with /translate, /translate/batch, /health, /cache/*, /presets
• Streamlit UI: interactive web interface for detection + translation

Quick Start

# Install
pip install -e .

# Single file
comic-translator page.jpg -o translated.png --translator google

# Batch with OpenAI
comic-translator manga_chapter/ --translator openai --model gpt-4o-mini --api-key sk-...

# Use a provider preset (auto api_base + model)
comic-translator chapter/ --translator openai --provider deepseek --preset manga-jp

# Start API server
comic-translator-server --port 8000

# Streamlit UI
streamlit run streamlit_app.py

Architecture

comic_translator/
├── cli.py              # CLI entry point (argparse)
├── server.py           # FastAPI REST API
├── config.py           # Layered config (defaults → env → CLI)
├── presets.py          # Preset profiles
├── providers.py        # LLM provider definitions
├── detection/          # Bubble detection (contour + OCR-first)
├── ocr/                # easyocr wrapper (lazy-loaded)
├── translation/        # Translator backends + cache + factory
│   ├── google.py       # deep-translator (Google Translate)
│   ├── openai.py       # OpenAI-compatible ChatCompletion
│   ├── dummy.py        # No-op pass-through
│   ├── fallback.py     # Sequential fallback chain
│   ├── factory.py      # Translator creation + caching wrapper
│   ├── glossary.py     # Term substitution
│   └── cache.py        # SQLite translation cache
├── rendering/          # PIL text rendering + inpainting
├── preprocessing.py    # CLAHE, sharpen, denoise, deskew
├── export.py           # CBZ, PDF, EPUB export
├── langdetect.py       # Source language auto-detection
└── utils/              # .env loader, font auto-detection

CLI Reference

Flag	Description
--translator	google, openai, dummy (default: google)
--provider	LLM provider: openai, deepseek, gemini, groq, together, ollama, openrouter, xai, cerebras
--preset	manga-jp, manga-en, webtoon, quick
--detect-method	contour (OpenCV) or ocr (OCR-first flood fill)
--preprocess	Enhance image before OCR
--source-lang	Source language or auto
--target-lang	Target language (default: tr)
--skip-sfx	Skip sound effects
--split-spreads	Auto-split double-page spreads
--workers	Parallel workers for batch
--watch	Watch directory for new images
--force	Reprocess already-translated pages
--resume-from	Resume batch from index
--export	cbz, pdf, epub
--report	csv, xlsx batch report
--text-only	Extract text only (JSON)
--dry-run	OCR only, no translation
--compare	Side-by-side comparison image
--debug-bubbles	Colored confidence overlay
--webhook	POST URL on batch complete
--log-file	File logging

API Server

comic-translator-server --port 8000 --api-key my-secret-key
# Docs: http://localhost:8000/docs

Endpoints:

• POST /translate — single image translation
• POST /translate/batch — ZIP upload batch translation
• GET /health
• GET /cache/stats, DELETE /cache
• GET /presets

Configuration

Layered config (lowest to highest priority):

1. Code defaults
2. ~/.config/comic-translator/config.json
3. Environment variables (CT_ prefix)
4. CLI arguments

comic-translator --init-config  # creates config.json

Dependencies

• opencv-python-headless, easyocr, Pillow, numpy
• deep-translator (Google Translate)
• requests (OpenAI API)
• tqdm (progress bars)
• Optional: fastapi, uvicorn (API), streamlit (UI), openpyxl (XLSX reports)

License

MIT