TranslateBooksWithLLMs: a desktop app for translating EPUB, SRT, DOCX and TXT with local or cloud LLMs

The gap TBL fills: full-length documents, not paragraphs

Most LLM translation workflows are built around a text box. You paste a chapter, you get a chapter back, and anything longer than the context window is your problem. TranslateBooksWithLLMs (TBL) treats the document as the unit of work. The README describes it as a desktop app that translates books, subtitles and documents, with EPUB, SRT, DOCX and TXT as the supported formats, and it states there is no size limit: the chunking system handles content of any length while preserving context between segments.

The target user is someone with a file, not an API integration. A translator checking a draft novel, a reader who wants a foreign-language EPUB in their own language, a subtitle editor working through an SRT, or a developer who wants to compare how several models render the same book. The command line interface exists for the last group, and the desktop build exists for the first three. That split explains most of the design decisions in the repository.

How the pipeline works: chunking, checkpoints and format round-tripping

The repository layout shows a Flask application under src/web with a Socket.IO dependency in requirements.txt, which matches the README's claim that the interface opens at http://localhost:5000 in a browser. So the desktop build is a local server plus a bundled browser UI, not a native window. That matters for deployment: anything that can reach port 5000 can reach the app, and the .env.example exposes HOST with the comment that 127.0.0.1 restricts it to localhost while 0.0.0.0 opens all network interfaces.

Translation itself is chunked. The README says context is preserved between segments, which is the part that separates this from naive splitting: each chunk is sent with material from its neighbours so the model does not restart mid-scene. Format handling is per-format. For EPUB the claim is that formatting, styles and structure remain intact; for SRT, that timecodes stay synchronized. The dependencies support that reading: lxml for XML-shaped formats, mammoth and python-docx for DOCX, tiktoken for token counting.

Progress is stored in SQLite checkpoints. The docker-compose.yml mounts ./data and labels it "Checkpoints (SQLite) and uploaded source files - REQUIRED for resume capability to survive container restarts. Do NOT remove this mount." That is the most operationally important line in the file. Resume is not a feature of the translation engine; it is a property of that volume.

Two optional layers sit on top. A style preset can be extracted from sample books and applied to every chunk, which is the project's answer to register drift across a long novel. An Auto option derives a glossary and a style from the document itself, at the cost of one extra LLM call each before the job starts, and the README notes nothing is saved.

Installing TBL and translating your first EPUB

The fastest route is the prebuilt release. The README lists archives for Windows, macOS Intel and macOS Apple Silicon on the releases page. Extract, run TranslateBook.exe or ./TranslateBook, then open http://localhost:5000. First launch creates a TranslateBook_Data folder for settings. On macOS the README says to allow the app under System Settings > Privacy & Security on first launch.

If you prefer the source route, the prerequisites are Python 3.8+, Ollama and Git. The README gives this sequence:

git clone https://github.com/hydropix/TranslateBooksWithLLMs.git
cd TranslateBookWithLLM
ollama pull qwen3:14b

# Windows
start.bat

# Mac/Linux
chmod +x start.sh && ./start.sh

The web interface opens at http://localhost:5000. If Ollama will not connect, the troubleshooting table suggests checking that it is running and testing the endpoint directly:

curl http://localhost:11434/api/tags

For a first real job, drop an EPUB into the interface, pick source and target languages, and choose a provider. With Ollama selected, the model name must match something you have pulled; the README's troubleshooting row says to run ollama list and then ollama pull model-name when a model is not found. The output filename follows OUTPUT_FILENAME_PATTERN, whose default is {originalName} ({targetLang}).{ext}, so an English book translated to Chinese lands as book (Chinese).epub.

If you would rather script it, translate.py takes the same parameters. The README's first example is:

python translate.py -i book.epub -sl English -tl Chinese

Cloud providers follow the same shape with a provider flag, a key flag and a model flag. For OpenRouter the README shows:

python translate.py -i book.txt --provider openrouter \
    --openrouter_api_key YOUR_KEY -m anthropic/claude-sonnet-4 -tl French

Docker is the third path. The compose file pulls ghcr.io/hydropix/translatebookswithllms:latest, maps port 5000, and mounts translated_files, logs and data. Keep the data mount; without it, a container restart discards the checkpoints that make resume work.

Where TBL breaks down

The honest limitation is that TBL is a pipeline, not a quality guarantee. Nothing in the README describes automatic terminology enforcement, a shared translation memory across projects, or a review step. Glossary support exists, but the Auto mode derives it per document and saves nothing, so two books in the same series will not automatically share vocabulary. If consistent naming across a series matters, you supply the glossary yourself.

Resource cost is the second constraint. The free path runs a local model, and the README's own example pulls qwen3:14b. A thousand-page novel through a 14B model on a laptop is a long job, and the checkpoint system exists precisely because these jobs get interrupted. The optional Chatterbox TTS dependency in requirements.txt carries a warning that its numpy requirements may conflict, which is a reminder that the optional extras are not as frictionless as the core install.

Deployment scope is the third. The compose file publishes port 5000, and the .env.example comment on HOST makes clear that binding to 0.0.0.0 exposes the interface on the network. There is no mention of authentication, user accounts or per-user isolation anywhere in the repository files. Treat it as a single-user tool on a trusted machine. If you need a hosted, multi-tenant translation service, this is the wrong shape of software.

Finally, the provider list is wide but not uniform. Each cloud provider has its own key flag, its own model naming convention and its own rate limits. The .env.example notes that *_API_KEY variables accept comma-separated keys and that the rotation pool switches keys on HTTP 429, which is a useful escape hatch for free tiers but also a sign that quota management is left to you.

How TBL differs from DeepL and PDFMathTranslate

DeepL is the obvious comparison and the one people search for alongside this project. The difference in approach is fundamental. DeepL is a hosted neural machine translation service with a fixed model you do not choose; TBL is a client that routes your document to whichever LLM you point it at, including a model running on your own machine. DeepL will generally be faster and needs no GPU; TBL lets you pick a model per language pair, keep the text on your hardware with Ollama, and tune register with a style preset. If you want one consistent engine and a web form, DeepL is the simpler answer. If you want to compare how Claude, Gemini and a local Qwen render the same chapter, TBL is built for that.

PDFMathTranslate appears in the same searches and solves an adjacent problem. It targets PDF, where layout reconstruction is the hard part. TBL's documented formats are EPUB, SRT, DOCX and TXT, so a PDF is not in scope unless you convert it first. Choosing between them is mostly a question of input format, not translation quality.

Against generic document-translator projects on GitHub, the distinguishing pieces here are the checkpoint store, the style preset extraction, and the breadth of providers in one interface. Those are the features worth evaluating; the translation itself is whatever your chosen model produces.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-06, with v1.5.10 released the same day. Recent release cadence shows v1.5.8 and v1.5.9 on 2026-08-24 and v1.5.10 on 2026-09-06, so changes are arriving in small increments rather than long quiet periods.

The licence is AGPL-3.0. The practical implication for a reader deciding whether to adopt: if you modify TBL and offer it to users over a network, the AGPL's network clause is the part to read carefully, because it can require you to publish your modified source. Running it locally for your own documents is a different situation from hosting a modified version for others. That is a description of the licence, not legal advice; check with someone qualified if you plan to build a product on it.

Upgrade cost is low for the desktop path, since the release archives are self-contained and settings live in TranslateBook_Data. The Docker path is a pull of the ghcr.io image tag, and the data volume persists across it. The source path is heavier: requirements.txt pins aiofiles below 25.0 and tiktoken at 0.5.0 or above, and the optional LiteLLM and Chatterbox extras are deliberately excluded from the default install because of dependency conflicts. If you enable either, expect to manage that environment yourself.

Editorial conclusion

Adopt it if you already have Ollama running or hold a cloud API key and want a local, checkpointed pipeline for full-length books rather than a browser tab. Skip it if you need multi-user hosting, a shared translation memory, or a service that guarantees terminology consistency without you supplying a glossary. Before you commit a long book, verify three things: that your chosen model handles your target language acceptably (the project's own benchmark page is the reference), that the data directory survives your deployment (the compose file marks the ./data mount as required for resume), and that AGPL-3.0 fits how you plan to distribute anything you build on top of it.

Frequently asked questions

Official sources

1. hydropix/TranslateBooksWithLLMs on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases