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
• 💾 Private Bounded Cache — durable server-side SQLite uses scoped SHA-256 keys, mandatory TTL/cap, and private file modes; browser persistence is opt-in on trusted single-user devices
• 🔒 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 (isolated API and proxy roles)

Two non-root containers run the same translator image. The proxy sits in front of CWA and injects the overlay; the private API owns translation and cache state. Your CWA container stays completely untouched.

Browser ──► book-translator-proxy (:8084) ──► CWA (:8083, stock)
                 │ injects overlay on /read/ pages
                 └─ /bt-api → book-translator-api (:8390, private)

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 --build

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 validates the browser's existing HttpOnly CWA session for every protected API request; it does not put a translator credential in JavaScript or localStorage. The API is attached to the CWA network only so it can call the authenticated /ajax/emailstat probe and remains unpublished to the host. The Compose file builds the exact checked-out source into the local cwa-ebook-translate-plugin:local image. Official releases are verified source tags, so installation needs no container-registry account, package token, or signing key. To upgrade, check out the new release tag and run the same command.

Already have CWA running? Copy the book-translator-api and book-translator-proxy services plus their private network and named volume from docker-compose.yml, then point CWA_UPSTREAM at your existing CWA service. Keep the two roles separate in production; the legacy combined mode exists only for upgrade compatibility.

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;
    }

Set BT_PUBLIC_ORIGIN=https://books.example.com on the translator proxy service (use your exact reader origin). The injection proxy forwards that validated, fixed scheme and authority to CWA; it never trusts a browser's or upstream request's Host, Forwarded, or X-Forwarded-Proto value. HTTPS sessions and secure cookies therefore work without making those headers an implicit trust boundary.

Option 2: Unraid

Clone a release tag on the Unraid host and run ./install_unraid.sh. The script builds local/book-translator-api:latest from that checkout and installs the legacy API template without downloading a project-published image or requiring registry credentials. Docker may download the pinned public base image during the build. For the recommended proxy-injection topology, use the Compose instructions above.

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. The shipped bind-mount overlay uses cwa_session; because its API is cross-origin, set one exact BT_ALLOWED_ORIGINS value, keep BT_ALLOW_PRIVATE_LAN=false, and configure the exact CWA auth URL. The helper does not place a shared API secret in browser JavaScript. Its direct :8390 API route is HTTP-only, so the helper accepts only an http:// reader origin; for an HTTPS reader, use the recommended same-origin proxy or provide a separately reviewed TLS API route and custom apiUrl.

⚡ 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 translator image (set them on the role that uses them):

Remote fallback is an additive, fail-closed API contract. Both POST /translate and POST /translate/batch accept the optional JSON boolean allow_cloud_fallback; omission means false, and strings/numbers are rejected. The reader exposes an explicit privacy switch explaining that book text will leave the local deployment. That decision is kept only in the current book tab and is never restored from localStorage. Configuring a cloud provider as the primary provider is a separate operator decision and sends all normal translation requests to that provider.

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).

Cache schema v2 intentionally preserves an existing v1 table as translations_v1 but never serves those unscoped rows. The cache re-warms without a destructive migration. V2 stores no source paragraph and hashes tenant/book/chapter identifiers before persistence. Browser translations stay in memory unless window.BOOK_TRANSLATOR.persistCache = true is explicitly set; opt-in keys also include stable DOM position to separate repeated text in different contexts. Legacy bt_cache_v2_* localStorage entries are removed on upgrade.

The bundled injection proxy replaces any inbound forwarding chain with the immediate peer address it actually observed. Direct LAN clients therefore keep per-client API limits. When SWAG/Traefik/NPM is the immediate peer, the API sees that edge proxy as one client; enforce client-aware admission at the trusted edge or size the translator's downstream limit for the aggregate. This avoids accepting spoofable client IPs without an explicit real-IP trust configuration.

🏗️ Architecture

Browser ──► proxy role (:8080) ──► CWA (:8083, stock)
                │
                ├─ /bt-static/* → overlay js/css
                └─ /bt-api/* ──► API role (:8390) ──► providers
                                         │
                                         └─ SQLite cache (/app/data)

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). The shipped helper exposes that port over HTTP and therefore rejects HTTPS reader origins rather than creating a browser-blocked mixed-content deployment. For cross-origin cwa_session, set authMode: 'cwa_session' and sendCredentials: true in window.BOOK_TRANSLATOR, disable BT_ALLOW_PRIVATE_LAN, and list the one exact CWA reader origin. In token and forwarded modes the frontend uses credentials: 'omit', so CWA cookies are not disclosed to the API origin.

Both image roles declare appuser (101:102), run with zero capabilities, and support a read-only root filesystem. If you replace the Compose named volume with a host bind mount, create it with ownership 101:102; runtime ownership repair was intentionally removed.

/ping is liveness-only and /health plus /ready are shallow readiness checks; none contacts an LLM. The provider-backed /health/deep endpoint is operator-only and uses the same request budget and global provider gate as a translation. Authenticate it with X-BT-Token: this is BT_API_TOKEN when configured, otherwise the persisted /app/data/cleanup_token value.

/metrics reports request/cache counters, fixed HTTP status classes, bounded authentication/rate-limit/provider/work-budget outcomes, partial-batch segment failures, and bounded singleflight activity (active_entries, shared results, follower timeouts, and capacity rejections). Metric dimensions are defined by the server: routes, identities, book metadata, provider URLs, exception strings, source text, and cache keys are never labels. Counters are process-local, which is another reason the shipped runtime intentionally uses one gunicorn worker.

Authentication-derived tenant behavior is intentional:

• cwa_session isolates by the current session hash. Logging out/re-authenticating creates a cold tenant because CWA v4.0.6 does not expose a stable supported current-user JSON identity at this boundary.
• forwarded isolates by the stable subject asserted by an allowlisted identity proxy and is the mode to use when cache continuity across sessions matters.
• token is one shared tenant. disabled is one anonymous tenant and must not be used for production.

Release operators should follow the Gitea-authoritative source release runbook; GitHub is a public source mirror and neither service publishes container images. See the architecture overview for component details and accepted architecture decision records. The production-readiness record maps the latest audit findings to their repository controls and lists the remote promotion prerequisites that a source commit cannot establish.

❤️ 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

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.