TranslateBooksWithLLMs: a local-first desktop pipeline for whole-book translation
Translate full-length books and documents with Ollama, OpenAI-compatible, Gemini, Mistral, DeepSeek, Poe or OpenRouter. Preserves formatting. Resumes where you left off. No file size limits.
At a glance
- What is it?
- TBL wraps LLM providers behind a chunking and checkpointing layer so EPUB, SRT, DOCX and TXT files survive translation with their structure intact. The trade-off is that it is a desktop app with a browser UI, not a library, and the quality ceiling is set entirely by the model you point it at.
- Who is it for?
- Adopt TBL if you are translating long EPUB, SRT or DOCX files and you want the job to survive an interruption without losing the first four hundred segments, or if you want the whole thing to run against a local Ollama model with no data leaving the machine. Do not adopt it if you need a programmatic API to call from your own pipeline, or if you need to translate a format outside EPUB, SRT, DOCX and TXT.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap TBL fills is resumability, not translation quality
Sending a paragraph to an LLM and getting a translated paragraph back is a solved problem with a one-line prompt. Sending a three-hundred-page novel through the same call is not, because the failure modes change. A single API timeout at page two hundred and forty means the earlier work is gone unless something saved it. Context drifts across thousands of independent calls, so chapter twelve reads like it was written by a different person than chapter one. And the container format matters: an EPUB is a zip of XHTML plus a manifest, and a naive round trip through plain text destroys the stylesheet links and the reading order.
TBL is aimed at people who hit all three of those at once. The README describes the target as books, subtitles and documents, with EPUB, SRT, DOCX and TXT as the supported formats. The subtitle case is the one where the format problem is most visible: an SRT file is a list of timecodes paired with text, and any translation that reflows the text risks desynchronising the timings. The README claims SRT timecodes stay synchronised and that EPUB formatting, styles and structure remain intact. That claim is the core of the project's pitch, and it is the first thing worth testing on your own file before trusting it with a full run.
Chunking, context carry-over and the checkpoint file
The mechanism the README describes is an intelligent chunking system that splits a document into segments, translates each segment, and preserves context between them. That last part is doing real work. If each chunk were translated in isolation, pronouns and terminology would drift, so context from prior segments is carried into the next call. The README does not specify the exact window size or whether context is passed as raw prior text or as a summary, so treat the size of that context window as unknown until you read the source.
Progress is saved automatically. The README calls this a checkpoint system and says an interrupted translation resumes exactly where it left off. On first launch the app creates a TranslateBook_Data folder for settings, so the working state has a home on disk. If you are running the command line entry point instead of the desktop build, you should confirm where checkpoints are written before starting a long job, because that directory is what you would need to back up or copy between machines.
Two other features sit on top of the chunk loop. Reusable writing styles let you extract a style preset from sample books, or write one by hand, and apply it to every chunk so register, rhythm and imagery stay consistent. Auto glossary and auto style are the lazy version: pick Auto in the dropdown and the app derives both from the document being translated, at the cost of one extra LLM call each before the job starts. The README is explicit that nothing from the auto path is saved, which means a second run on the same book pays that cost again.
Running it: releases, source install, and the CLI flags
The fastest path is the prebuilt release. The README points at zipped archives for Windows, macOS Intel and macOS Apple Silicon, and the steps are to extract, run TranslateBook.exe on Windows or ./TranslateBook on macOS, then open http://localhost:5000 in a browser. On macOS the first launch requires going to System Settings, then Privacy & Security, and clicking Open Anyway, which is the standard Gatekeeper step for an unsigned binary.
Installing from source needs Python 3.8 or later, Ollama and Git. The commands in the README are:
git clone https://github.com/hydropix/TranslateBooksWithLLMs.git cd TranslateBookWithLLM ollama pull qwen3:14b
On Windows you then run start.bat; on macOS and Linux you run chmod +x start.sh && ./start.sh. The web interface comes up on port 5000 either way.
The CLI is a separate entry point, translate.py, and it is where the provider plumbing becomes visible. A basic run is python translate.py -i book.epub -sl English -tl Chinese, which auto-generates an output name like book (Chinese).epub. Provider selection is a --provider flag plus a matching API key flag and a -m model flag. The README shows openrouter with --openrouter_api_key, openai with --openai_api_key, gemini with --gemini_api_key, mistral with --mistral_api_key, deepseek with --deepseek_api_key, poe with --poe_api_key, and nim with --nim_api_key. There is also an OpenAI-compatible mode for local servers such as llama.cpp, LM Studio, vLLM and LocalAI, where you point the tool at your server's endpoint. Note that the README's own source-install block changes directory into TranslateBookWithLLM while the clone command creates TranslateBooksWithLLMs, a mismatch worth checking against the actual repository before you paste it.
Where the design bites: model dependency, format ceiling and no library API
The honest limitation is that TBL contributes orchestration, not translation. Every quality decision is delegated to the model behind the provider flag. The README links to a wiki page of translation quality benchmarks and tells you to find the best model for your target language, which is effectively an admission that the tool cannot compensate for a weak model. If you run it against a small local model and the output is poor, nothing in the chunking or style layer will rescue it.
The format list is a hard boundary. EPUB, SRT, DOCX and TXT are what the README names. A PDF, an ODT, an HTML page or a Markdown file are not listed. For a PDF in particular, the layout-preservation problem is much harder than for EPUB, and the project does not claim to solve it.
The architecture is also a desktop app with a browser front end, not a library you import. The README presents the web interface at localhost:5000 and a translate.py command line script, and there is no documented Python API for embedding the chunker in your own service. If your workflow is a CI job that translates documentation on every merge, you would be shelling out to translate.py and parsing its output, which is a thinner integration than a library would give you.
Finally, the auto glossary and auto style path adds two extra LLM calls before the first segment is translated, and the README says nothing is saved from it. On a paid provider that is a small but real cost per book, and it is paid again on every re-run.
Calibre plus a translation plugin, and how the approach differs
The closest thing to a direct comparison in this space is Calibre with an LLM translation plugin. Calibre is a mature ebook library manager with a plugin system, and translation plugins for it exist that call out to LLM APIs. The difference in approach is structural. Calibre owns the ebook: it parses the EPUB into its internal representation, and a plugin operates on that representation, which means format handling is inherited from a tool that has been doing it for years. What Calibre does not give you out of the box is a checkpoint system tuned for long translation runs, or a style preset extracted from sample books.
TBL inverts the priority. It treats the document as something to be chunked and streamed through a model, and it invests in the run management around that: resuming, context carry-over, style consistency, glossary derivation. Format preservation is a claim it makes rather than a capability it inherits from a decade-old ebook engine. Which one is right depends on what you are more afraid of: a plugin ecosystem where translation support depends on which plugin you picked, or a purpose-built tool whose EPUB handling you have to verify yourself on your own files.
Licence and the cost of staying current
The repository is AGPL-3.0. For someone running TBL locally to translate their own books, that is unremarkable. For anyone who wants to take the chunking and checkpointing code and put it inside a hosted service, the AGPL's network-use clause is the thing to read carefully, and the answer depends on facts about your deployment that this article cannot evaluate. If that describes your situation, get your own legal read rather than relying on a summary.
The release cadence visible in the supplied material is three releases in roughly two weeks in August and September 2026, v1.5.8 through v1.5.10. That is a fast-moving project, which cuts both ways: fixes arrive quickly, and the surface you tested against may shift under you. The practical implication is that pinning a specific release for a long translation job is safer than always pulling latest, particularly if you have tuned prompts or style presets against the behaviour of one version. The README also points to a docs folder with PROVIDERS.md and TROUBLESHOOTING.md, so provider-specific setup and connection failures have documented answers rather than requiring a source dive. For Ollama connection problems the README's own diagnostic is curl http://localhost:11434/api/tags, and for a missing model it is ollama list followed by ollama pull model-name.
Editorial conclusion
Adopt TBL if you are translating long EPUB, SRT or DOCX files and you want the job to survive an interruption without losing the first four hundred segments, or if you want the whole thing to run against a local Ollama model with no data leaving the machine. Do not adopt it if you need a programmatic API to call from your own pipeline, or if you need to translate a format outside EPUB, SRT, DOCX and TXT. Before committing, verify three things: that your chosen provider and model actually hold the target language across a full chapter, that the checkpoint files land somewhere your backup covers, and that the AGPL-3.0 obligations are acceptable for how you intend to distribute anything derived from the code.
Community notes