CWA eBook Translate Plugin

Bilingual LLM-powered translation overlay for Calibre-Web-Automated. Translate ebooks paragraph-by-paragraph while reading — in 100+ languages — using local LLMs (vLLM, LM Studio, Ollama) or any major Cloud API (OpenAI, Anthropic, Gemini, Groq, Together, MiniMax, DeepSeek, OpenRouter).

✨ Features

• 🌐 Bilingual reading — original + translation side by side
• 🔄 Three modes — Bilingual / Translation-only / Original
• 🌍 100+ target languages — the picker shows the 10 most-spoken languages first, then every other supported language A–Z (type to jump). Developed and tuned against Google's Gemma 4 as the default local model; the language set mirrors Gemma's pre-training coverage
• ⚡ Visible-First Translation — prioritizes paragraphs visible on screen for instant rendering
• 🚀 Background Prefetching — translates the rest of the chapter sequentially in the background
• 🧠 Context-Aware Translation — feeds surrounding paragraphs to the LLM to improve literary quality and character voice
• 📚 Deep DOM Parsing — accurately captures headings, custom title classes, and clickable TOC links
• 💾 Persistent Double Cache — server-side SQLite (SHA-256) + client-side localStorage caching ensures you never lose a translation or re-pay API costs
• 🔒 Rate limited & Stable — request-size caps and per-IP rate limiting protect your API keys and GPU from runaway requests, with AbortController cancellation for perfectly responsive UI buttons
• 🔌 Zero-touch install — proxy-injection mode overlays a stock CWA container: no template mounts, nothing to re-apply when CWA updates

A note on language quality

The default model, Gemma 4 (gemma4-12b), is pre-trained on 140+ languages with ~35 languages receiving first-class, benchmarked support (all major European, East Asian, South/Southeast Asian, and Middle Eastern languages). The remaining languages in the picker come from Gemma's wider pre-training corpus: translation works, but lower-resource languages (e.g. Nahuatl, Chewa, Tibetan) can occasionally lose coherence or bleed into a dominant language on complex passages. Cloud models (GPT, Claude, Gemini) generally handle the lower-resource tier better — switch LLM_PROVIDER if a language matters to you.

🚀 Installation

Recommended: proxy-injection mode (one extra container, stock CWA)

The translator container sits in front of CWA and injects the overlay into reader pages on the fly. Your CWA container stays completely untouched.

Browser ──► book-translator (:8084) ──► Calibre-Web-Automated (:8083, stock)
                 │ injects overlay on /read/ pages
                 └─ /bt-api → translation API (same origin, no CORS)

git clone https://github.com/felixapel/CWA-eBook-Translate-Plugin.git
cd CWA-eBook-Translate-Plugin
# Edit docker-compose.yml: set BT_LOCAL_URL (or a cloud provider + API key)
docker compose up -d

Then read your library at http://<host>:8084 — the translator control bar appears in the ebook reader. That's the whole install. The compose file pulls the prebuilt multi-arch image (ghcr.io/felixapel/cwa-ebook-translate-plugin, amd64 + arm64) — no build step needed.

Already have CWA running? Add just the translator service to your existing compose file and point CWA_UPSTREAM at your CWA container/host:

  book-translator:
    image: ghcr.io/felixapel/cwa-ebook-translate-plugin:latest
    environment:
      - CWA_UPSTREAM=http://calibre-web-automated:8083
      - BT_LOCAL_URL=http://host.docker.internal:11434/v1/chat/completions
    extra_hosts: ["host.docker.internal:host-gateway"]
    volumes: ["./config/translator:/app/data"]
    ports: ["8084:8080"]   # read CWA (with overlay) here — any free port works
    restart: unless-stopped

Removing the plugin = stop reading through the proxy port. Nothing in your CWA install was modified.

Behind a reverse proxy (SWAG / Traefik / NPM / Cloudflare)

If you already expose CWA on a domain, point your reverse proxy's main location at the translator's proxy port instead of CWA's port — the overlay then works on your domain with the API same-origin (no CORS, no extra routes). Verified SWAG example (only the main location changes; keep OPDS/Kobo sync locations pointing directly at CWA):

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app 10.0.0.10;        # docker host (substitute your own)
        set $upstream_port 8084;            # translator proxy port (NOT CWA's)
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }

The injection proxy forwards your reverse proxy's X-Forwarded-Proto, so HTTPS sessions and secure cookies keep working.

Option 2: Unraid

Community Applications (recommended once listed): search for "CWA eBook Translate" in the Apps tab. Until the listing is approved, add the template manually — Docker tab → Add Container → Template repositories → add https://github.com/felixapel/unraid-templates, or download the template XML into /boot/config/plugins/dockerMan/templates-user/. The template installs proxy-injection mode: set CWA URL to your CWA instance and read through this container's port — your CWA container stays stock.

Legacy: bind-mount installer script

install_unraid.sh copies the overlay files into your CWA appdata folder and installs an Unraid Docker template for the API (bind-mount method). Review the script, then run it locally (don't pipe an unreviewed remote script into bash):

git clone https://github.com/felixapel/CWA-eBook-Translate-Plugin.git
cd CWA-eBook-Translate-Plugin
chmod +x install_unraid.sh
./install_unraid.sh

Post-Install Steps:

1. Go to your Unraid Docker tab and edit your calibre-web-automated container.
2. Add the 3 paths (as instructed by the script) to inject the plugin files.
3. Deploy the newly added book-translator-api container.

deploy_unraid.sh / verify_unraid.sh are personal SSH-based redeploy/verify helpers for an existing install — read them and adapt the host/paths before use.

Tip: proxy-injection mode also works on Unraid (run the container with CWA_UPSTREAM set and browse through its port) and avoids the 3 path mappings entirely.

Advanced: bind-mount install (development / no proxy)

Mount the overlay files directly into the CWA container — useful when hacking on the overlay itself:

volumes:
  - ./overlay/read.html:/app/calibre-web-automated/cps/templates/read.html:ro
  - ./static/translator.js:/app/calibre-web-automated/cps/static/js/translator.js:ro
  - ./static/translator.css:/app/calibre-web-automated/cps/static/css/translator.css:ro

Caveats: overlay/read.html is a full template replacement tracked against the pinned CWA version in docker-compose.yml (v4.0.6). A CWA update that changes read.html can drift from this copy — proxy mode does not have this problem. With bind mounts the API is cross-origin, so set BT_ALLOWED_ORIGINS (or rely on the private-LAN default) and configure window.BOOK_TRANSLATOR in overlay/read.html.

⚡ Performance

Throughput and latency depend entirely on your LLM backend (local GPU/model vs. a cloud API) and on the tunables in Configuration — there is no single number that applies to every setup, so we don't publish one. Two scripts are included so you can measure your deployment:

• benchmark.py — quick concurrent load test against a running API.
• benchmark_realistic.py — simulates a realistic reading session (visible-page + background prefetch) against a live backend.

Run either with the API up (python benchmark.py / python benchmark_realistic.py) and read the printed p50/p95/throughput for your own hardware.

If cold translations feel slow, see BT_BATCH_SIZE, BT_OUTPUT_TOKEN_FACTOR, and BT_MAX_CONCURRENT below, and docs/TROUBLESHOOTING.md.

⚙️ Configuration

Environment variables for the book-translator container:

Why a single gunicorn worker? Rate limiting, request metrics, and the health cache are kept in process memory for simplicity. Running more than one worker would give each its own copy (e.g. the rate limit becoming N× the configured value). The --threads 8 setting already gives plenty of request concurrency within that one worker — don't raise --workers without moving that state to something shared (e.g. SQLite, like the translation cache already is).

🏗️ Architecture

                       book-translator container
                 ┌───────────────────────────────────────┐
Browser ────────►│ nginx (:8080, proxy mode only)        │      ┌──────────────────────┐
  reads library  │  ├─ /bt-api/*    → gunicorn (below)   │─────►│ CWA (:8083, stock)   │
  through :8084  │  ├─ /bt-static/* → overlay js/css     │      │ untouched image      │
                 │  └─ /*           → CWA + injected tag │      └──────────────────────┘
                 │                                       │
                 │ gunicorn (:8390, always on)           │      ┌──────────────────────┐
                 │  ├─ POST /translate, /translate/batch │─────►│ Providers: local,    │
                 │  ├─ GET  /ping /health /metrics /stats│      │ OpenAI, Anthropic,   │
                 │  └─ SQLite cache (/app/data)          │      │ Gemini, Groq, ...    │
                 └───────────────────────────────────────┘      └──────────────────────┘

In bind-mount installs nginx never starts; the overlay files are mounted into CWA and call the API on :8390 directly (CORS applies — see BT_ALLOWED_ORIGINS).

❤️ Support the project

CWA eBook Translate is free, GPL-licensed, and has no telemetry, ads, or subscription — if it replaced a paid translation service for you, consider funding its development:

• Ko-fi — quick one-time tips, 0% platform fees
• GitHub Sponsors — monthly support (enrollment in progress)

Donations fund GPU time for multi-model testing, coverage of the 100+ language matrix, and maintainer time on issues. Non-monetary support counts just as much: ⭐ star the repo, report bugs with reproducible steps, test new releases, or bring a translation of the UI strings.

📜 License

GPL-3.0. This project extends Calibre-Web-Automated (itself GPL-licensed), and the advanced bind-mount install ships a template derived from it — so the whole project is licensed under the GNU GPL v3 to keep everything clean and compatible. See LICENSE.

This project is not affiliated with, endorsed by, or sponsored by Calibre-Web, Calibre-Web-Automated, Calibre, Google (Gemma), or any LLM provider. All names are used nominatively to describe compatibility.