Professional literary translation software for translating entire TXT, EPUB, PDF, and DOCX books with local Ollama models, document glossaries, guarded refinement, and side-by-side review.
# macOS / Linux
git clone https://github.com/KazKozDev/book-translator.git && cd book-translator && python3 launch.py
# Windows (PowerShell or cmd, after cloning)
git clone https://github.com/KazKozDev/book-translator.git
cd book-translator
py -3 launch.py
Launchers after clone — double-click .command / .bat, or run .sh.
demo-readme.mp4
-
Run the command above. On macOS and Linux it clones the repository and starts
launch.py; on Windows, clone first, then runpy -3 launch.pyor double-clickLaunch Book-Translator.bat. The launcher createsvenv, installs the Python dependencies, checks Ollama and the required local models, starts Tolmach athttp://localhost:5001, and opens it in your browser. -
Open Settings, choose a local model for each role, and click Save setup.
-
Return to the main page and follow the numbered buttons:
→ 1 UPLOAD → PREPARE (optional) → 2 START → 3 CONTINUE → TXT / PDF / EPUBSTART creates the first translation. CONTINUE reviews and refines it. When the job finishes, use the export buttons to download the book.
Choose the source language, target language, and text genre. Click → 1 UPLOAD and select the complete book—not one chapter at a time.
Source language: English
Target language: Russian
Input: TXT, EPUB, PDF, or DOCX
Download: TXT, PDF, or EPUB
A PDF is read for its text only. Tolmach removes running heads and page numbers and rejoins the printed lines back into paragraphs; bookmarks or clear chapter headings become chapter breaks when detected. Layout and images are not carried over. A scanned PDF with no text layer is refused — run OCR first, or use TXT, EPUB, or DOCX. A DOCX keeps Heading 1 sections as chapters when present.
Click → 2 START to create the draft translation. Finished sections appear in the Translation panel while the rest of the book continues processing. Click → 3 CONTINUE when you want Tolmach to refine that draft into the final version.
The job is saved locally, so you can reopen it from the Archive. A complete book can take 10–15 hours; the actual time depends on its length, your models, and your computer.
The translation desk stays the same across targets. Click a thumbnail for the full screenshot.
 ru_RU |
 es_ES |
 fr_FR |
 de_DE |
 it_IT |
 pt_BR |
 zh_CN |
 ja_JP |
 ko_KR |
After uploading the book, click → PREPARE. Tolmach scans the complete source and creates an editable glossary of recurring names, places, organisations, and terms.
Netherfield => Незерфилд | exact
Mr. Darcy => мистер Дарси | inflectable
Review this list before starting the translation: delete noise, correct a wrong translation, and add anything the scan missed.
exactkeeps the target wording unchanged.inflectablelets the model change the grammatical form.preferredtells the model which wording to favor.
The glossary belongs only to this book and language pair. If you configure an optional external provider, Verify automatically can check the glossary and show proposed changes; Tolmach applies nothing until you approve it.
After → 3 CONTINUE finishes, open Review desk. Each chunk shows the original source, the first draft, and the editable final translation next to each other.
Proposed fixes can be applied manually, decided and saved by the configured cloud provider for one chunk, or processed for every open chunk with Review all automatically. Cloud decisions are restricted to apply/keep for the existing proposed fixes; they cannot rewrite the chunk or invent another option.
Source → Draft → Final → Save final → Download
Start with Needs review, inspect the proposed fixes, and apply only the changes you want. You can edit the final text directly or ask for two or three alternatives. Tolmach never replaces your final choice automatically.
Optional quality checks flag possible terminology errors, missing text, changed numbers, wrong-language passages, repetition, and meaning drift. They are diagnostics: they do not rewrite the book or prevent export.
The browser sends your TXT, EPUB, PDF, or DOCX to a Flask server running on your computer.
PREPARE scans the whole book and builds a glossary for that document.
START splits the book into chunks and translates them with the selected Ollama model.
CONTINUE proposes small edits, and a separate verifier checks each edit against the source.
SQLite saves the job, glossary, aligned text, review state, quality results, and cache locally.
Book → Glossary → Draft translation → Verified refinement → Human review → Download
Technical architecture
- Upload — the Flask backend reads TXT, EPUB, PDF, or DOCX and stores the source in
uploads/. A PDF is read as text (with chapter breaks from bookmarks/headings when detected); a DOCX uses Heading 1 sections as chapters when present. - Prepare — deterministic text harvesting and GLiNER collect entity candidates. BGE-M3 groups likely spelling variants, then the selected instruct model resolves ambiguous groups and proposes target renderings. The editable glossary is stored for this document fingerprint and language pair.
- Start — the source is split into chunks of about 1200 characters at paragraph and sentence boundaries. The Translation model receives each chunk with its genre, glossary constraints, and previous-paragraph context. Completed chunks are written to SQLite and streamed to the browser.
- Continue — unlike a typical LLM “improve this” pass that rewrites the whole chunk and can replace already-good wording, the Refinement model returns located edits instead of rewriting an entire chunk. Python applies only those replacements. The Verifier compares each patched version with the source, checks the alternatives in both orders, and retries without ordered A/B versions when it detects position bias.
- Review and export — Review desk keeps Source, Draft, and editable Final text aligned. Exporters write the accepted final text as TXT, PDF, or EPUB.
Browser
↓
Flask UI + JSON API
↓
Prepare → Start → Continue → Review
↓ ↓ ↓
Glossary Ollama Verifier
└───────── SQLite ─────────┘
↓
TXT / PDF / EPUB
translations.dbstores jobs, aligned chunks, glossary drafts, review state, and saved quality results.cache.dbstores completed chunk translations so resumed jobs do not repeat finished work.- Deterministic checks inspect the complete document for missing chunks, changed numbers, glossary violations, source-script leakage, unusual length, and repetition.
- Optional model checks include draft/final LLM judging, backtranslation chrF, LaBSE alignment, language identification, and COMET-Kiwi. They report evidence but do not edit the translation.
launch.py— cross-platform bootstrap used by the macOS, Linux, and Windows launchers.src/translator.py— Flask application, API, translation stages, persistence, and export orchestration.src/frontier_glossary.py— optional external glossary verification.src/quality_tests.py— deterministic and model-based quality checks.src/terminology.py— glossary parsing and enforcement rules.src/epub_io.py— EPUB input and output.src/pdf_io.py— PDF input: text extraction and paragraph reconstruction.src/translation_cache.py— persistent chunk cache.src/prompts/— prompts sent to each model role.src/static/— browser interface, Settings, Guide, and live Log pages.tests/— model-free unit and integration tests.
Configuration
| Setting | Default | What it means |
|---|---|---|
| App address | http://localhost:5001 |
Local browser interface; set PORT to change the port |
| Ollama address | http://localhost:11434 |
Local server that runs the language models |
| Translation model | translategemma:12b preferred |
Creates the first translation during START |
| Glossary model | First suitable local instruct model | Builds glossary suggestions during PREPARE |
| Refinement model | First suitable local instruct model | Proposes improvements during CONTINUE |
| Verifier model | A model different from Refinement | Checks whether proposed edits preserve the source meaning |
| Judge model | A model different from Translation | Runs optional translation-quality diagnostics |
| Chunk size | 1200 characters |
Splits first on paragraphs, then on sentence boundaries |
| Source language | English | Chosen separately for each book |
| Target language | Spanish | Chosen separately for each book |
| Text genre | Unknown / Auto | Also supports Fiction, Technical, Academic, Business, and Poetry |
| Glossary verification | Off | Optional: configure OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY |
| COMET-Kiwi access | Off | Optional: set HF_TOKEN after receiving access to the gated model |
Requirements
- macOS or Linux for the one-command installer. Windows users can run the repository launcher.
- Ollama running on the same computer.
- The minimum local setup is
translategemma:12bfor translation plusgemma4:31bfor the other roles. For a more independent refinement check, choose a third instruct model as Verifier. - A stack that personally produced good results for the author: Glossary preparation
gemma4:31b-cloud(32.7B), Translationtranslategemma:27b(27.4B), Refinementgemma4:31b-cloud(32.7B), Verifier and Judgemistral-large-3:675b-cloud(675B) (cloud open-source models). - Enough memory and disk space for the models you choose.
- Internet access on the first run to download Python dependencies, Ollama models, and optional Hugging Face components.
- Supported languages: English, Russian, Spanish, French, German, Italian, Portuguese, Chinese, Japanese, and Korean.
The installer uses an existing Python 3.10+ installation when available. Otherwise, it installs Python 3.12 through uv.
Limitations
- Tolmach is not a one-prompt translator. A finished book needs the staged workflow (glossary → START → CONTINUE → review) and several local model roles working in sequence; expecting chat-app turnaround will disappoint.
- Translation quality depends heavily on the model stack. A stack that personally produced good results for the author is Glossary preparation
gemma4:31b-cloud(32.7B), Translationtranslategemma:27b(27.4B), Refinementgemma4:31b-cloud(32.7B), Verifier and Judgemistral-large-3:675b-cloud(675B) (cloud open-source models). Smaller local models still run; expect lower quality. - A long Start run keeps going if you close the browser tab; use Resume in History to continue from the last finished chunk after an interrupt or server restart. A full machine sleep or Ollama crash still stops the model calls themselves.
- Tolmach accepts TXT, EPUB, PDF, and DOCX. A scanned PDF without a text layer is refused; layout/images are not preserved.
- Translating a complete book can take 10–15 hours on local hardware.
- Translation and review models can still miss errors or make good text worse. Proofread the final book before publishing it.
- Large Ollama models need substantial memory and disk space; Tolmach cannot make a model fit hardware that is too small.
- Optional glossary verification sends the glossary and language pair—not the full book—to the selected API provider and may cost money.
- COMET-Kiwi is optional, downloads a multi-gigabyte gated checkpoint, and requires Hugging Face access.
- Tolmach does not currently provide an official Docker image.
Manual installation, Docker, development setup
git clone https://github.com/KazKozDev/book-translator.git
cd book-translator
python3 launch.pylaunch.py creates the virtual environment, installs runtime dependencies, checks Ollama and the required models, starts the server, and opens the browser.
The platform launchers use the same setup:
- macOS: double-click
Launch Book-Translator.command - Linux: run
./Launch Book-Translator.sh - Windows: double-click
Launch Book-Translator.bat
To use optional glossary verification, copy .env.example to .env.local and add the provider key. On macOS and Linux, set the file permissions to 600.
This repository does not currently include a Dockerfile or published image. Use the native launcher so Tolmach can detect Ollama, installed models, and local hardware.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
python -m pytest tests -q
ruff check .The test suite does not require Ollama, downloaded models, or network access.
Tolmach Book Translator is free and open-source software licensed under the GNU Affero General Public License version 3 only (AGPL-3.0-only).
Issues · Changelog · Contributing · LICENSE · DISCLAIMER · LinkedIn