book-translator - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #typescript #golang #go #android #deep-learning #docker #nodejs #awesome #cli #awesome-list #vue #mcp

book-translator

(★ 84)

Offline AI book translator for EPUB, PDF, and TXT. Translate entire books and novels locally with Ollama, document glossaries, refinement, and side-by-side review.

File Explorer

Download Latest Version (.zip)

- - bug_report.yml
  - config.yml
  - feature_request.yml
- - ci.yml
- PULL_REQUEST_TEMPLATE.md
- - linux.png
  - macos.png
  - windows.png
- - tolmach-launch-bed.mp3
  - tolmach-launch-bed.wav
- - de_DE.png
  - es_ES.png
  - fr_FR.png
  - it_IT.png
  - ja_JP.png
  - ko_KR.png
  - pt_BR.png
  - ru_RU.png
  - zh_CN.png
- demo-launch-video.mp4
- demo-launch.gif
- demo-launch.mp4
- demo-polished.gif
- demo-readme.mp4
- demo.gif
- social-preview.jpg
- social-preview.png
- tolmach-tail-intro.gif
- tolmach-youtube-thumbnail.png
- youtube-thumbnail.jpg
- youtube-thumbnail.png
- - README.md
- - guide.html
  - index.html
  - logs.html
  - settings.html
- banner.py
- build_glossary.py
- docx_io.py
- epub_io.py
- frontier_glossary.py
- frontier_review.py
- languages.py
- monitoring.py
- pdf_io.py
- prompts.py
- quality_tests.py
- terminology.py
- translation_cache.py
- translator.py
- - glossary-smoke.txt
- conftest.py
- test_chunk_review.py
- test_document_checks.py
- test_docx_upload.py
- test_epub_export.py
- test_frontier_glossary.py
- test_frontier_review.py
- test_glossary_builder.py
- test_glossary_verification_prompt.py
- test_installer.py
- test_launcher.py
- test_log_stream.py
- test_long_run_resume.py
- test_model_role_wiring.py
- test_pdf_chapters.py
- test_pdf_upload.py
- test_prepare.py
- test_prompts.py
- test_recovery_routes.py
- test_refinement.py
- test_run_locking.py
- test_terminal_banner.py
- test_terminology.py
- test_translategemma.py
- test_uploads.py
- test_workspace_glossary.py
.env.example
.gitignore
CHANGELOG.md
CONTRIBUTING.md
DISCLAIMER.md
install.sh
Launch Book-Translator.bat
Launch Book-Translator.command
Launch Book-Translator.sh
launch.py
LICENSE
pyproject.toml
README.md
requirements-dev.txt
requirements.txt
SECURITY.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Tolmach — AI Book Translator for EPUB, PDF, and Novels

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.

```bash
# 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
```

<p align="center">
  <a href="Launch%20Book-Translator.command"><img src="assets/badges/macos.png" alt="macOS" height="36"></a>
  <a href="Launch%20Book-Translator.bat"><img src="assets/badges/windows.png" alt="Windows" height="36"></a>
  <a href="Launch%20Book-Translator.sh"><img src="assets/badges/linux.png" alt="Linux" height="36"></a>
</p>

<p align="center">Launchers after clone — double-click <code>.command</code> / <code>.bat</code>, or run <code>.sh</code>.</p>

<p align="center">
  <video src="https://github.com/user-attachments/assets/eae8eae5-6ca9-4b2c-8f67-cf7a39848794" controls muted playsinline width="820">
    Your browser does not support inline video.
    <a href="https://www.youtube.com/watch?v=-lMNAKOp1Kc" target="_blank" rel="noopener noreferrer">Watch on YouTube</a>
  </video>
</p>

---

## Quick start

1. Run the command above. On macOS and Linux it clones the repository and starts `launch.py`; on Windows, clone first, then run `py -3 launch.py` or double-click `Launch Book-Translator.bat`. The launcher creates `venv`, installs the Python dependencies, checks Ollama and the required local models, starts Tolmach at `http://localhost:5001`, and opens it in your browser.

2. Open **Settings**, choose a local model for each role, and click **Save setup**.

3. Return to the main page and follow the numbered buttons:

```text
   → 1 UPLOAD → PREPARE (optional) → 2 START → 3 CONTINUE → TXT / PDF / EPUB
   ```

**START** creates the first translation. **CONTINUE** reviews and refines it. When the job finishes, use the export buttons to download the book.

## Translate an entire EPUB or PDF book with AI

Choose the source language, target language, and text genre. Click **→ 1 UPLOAD** and select the complete book—not one chapter at a time.

```text
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.

## Same desk, nine target languages

The translation desk stays the same across targets. Click a thumbnail for the full screenshot.

<table>
  <tr>
    <td align="center"><a href="assets/locales/ru_RU.png"><img src="assets/locales/thumbs/ru_RU.png" alt="Tolmach translating English to Russian" width="260"></a><br><code>ru_RU</code></td>
    <td align="center"><a href="assets/locales/es_ES.png"><img src="assets/locales/thumbs/es_ES.png" alt="Tolmach translating English to Spanish" width="260"></a><br><code>es_ES</code></td>
    <td align="center"><a href="assets/locales/fr_FR.png"><img src="assets/locales/thumbs/fr_FR.png" alt="Tolmach translating English to French" width="260"></a><br><code>fr_FR</code></td>
  </tr>
  <tr>
    <td align="center"><a href="assets/locales/de_DE.png"><img src="assets/locales/thumbs/de_DE.png" alt="Tolmach translating English to German" width="260"></a><br><code>de_DE</code></td>
    <td align="center"><a href="assets/locales/it_IT.png"><img src="assets/locales/thumbs/it_IT.png" alt="Tolmach translating English to Italian" width="260"></a><br><code>it_IT</code></td>
    <td align="center"><a href="assets/locales/pt_BR.png"><img src="assets/locales/thumbs/pt_BR.png" alt="Tolmach translating English to Portuguese" width="260"></a><br><code>pt_BR</code></td>
  </tr>
  <tr>
    <td align="center"><a href="assets/locales/zh_CN.png"><img src="assets/locales/thumbs/zh_CN.png" alt="Tolmach translating English to Chinese" width="260"></a><br><code>zh_CN</code></td>
    <td align="center"><a href="assets/locales/ja_JP.png"><img src="assets/locales/thumbs/ja_JP.png" alt="Tolmach translating English to Japanese" width="260"></a><br><code>ja_JP</code></td>
    <td align="center"><a href="assets/locales/ko_KR.png"><img src="assets/locales/thumbs/ko_KR.png" alt="Tolmach translating English to Korean" width="260"></a><br><code>ko_KR</code></td>
  </tr>
</table>

## Use an AI book translator with a glossary

After uploading the book, click **→ PREPARE**. Tolmach scans the complete source and creates an editable glossary of recurring names, places, organisations, and terms.

```text
Netherfield => Незерфилд | exact
Mr. Darcy => мистер Дарси | inflectable
```

Review this list before starting the translation: delete noise, correct a wrong translation, and add anything the scan missed.

- `exact` keeps the target wording unchanged.
- `inflectable` lets the model change the grammatical form.
- `preferred` tells 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.

## Review a novel translation side by side

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.

```text
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.

## How it works

The browser sends your TXT, EPUB, PDF, or DOCX to a Flask server running on your computer.<br>
**PREPARE** scans the whole book and builds a glossary for that document.<br>
**START** splits the book into chunks and translates them with the selected Ollama model.<br>
**CONTINUE** proposes small edits, and a separate verifier checks each edit against the source.<br>
SQLite saves the job, glossary, aligned text, review state, quality results, and cache locally.

```text
Book → Glossary → Draft translation → Verified refinement → Human review → Download
```

<details>
<summary>Technical architecture</summary>

### Translation pipeline

1. **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.
2. **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.
3. **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.
4. **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.
5. **Review and export** — Review desk keeps Source, Draft, and editable Final text aligned. Exporters write the accepted final text as TXT, PDF, or EPUB.

```text
Browser
   ↓
Flask UI + JSON API
   ↓
Prepare → Start → Continue → Review
   ↓         ↓         ↓
Glossary   Ollama   Verifier
   └───────── SQLite ─────────┘
                   ↓
             TXT / PDF / EPUB
```

### Storage and quality checks

- `translations.db` stores jobs, aligned chunks, glossary drafts, review state, and saved quality results.
- `cache.db` stores 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.

### Important files

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

</details>

<details>
<summary>Configuration</summary>

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

</details>

<details>
<summary>Requirements</summary>

- **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:12b` for translation plus `gemma4:31b` for 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), Translation `translategemma:27b` (27.4B), Refinement `gemma4:31b-cloud` (32.7B), Verifier and Judge `mistral-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`.

</details>

<details>
<summary>Limitations</summary>

- 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), Translation `translategemma:27b` (27.4B), Refinement `gemma4:31b-cloud` (32.7B), Verifier and Judge `mistral-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.

</details>

<details>
<summary>Manual installation, Docker, development setup</summary>

### Manual installation

```bash
git clone https://github.com/KazKozDev/book-translator.git
cd book-translator
python3 launch.py
```

`launch.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`.

### Docker

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.

### Development setup

```bash
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.

</details>

## License

Tolmach Book Translator is free and open-source software licensed under the [GNU Affero General Public License version 3 only](LICENSE) (`AGPL-3.0-only`).

<br><br>

<p align="center">
  <a href="https://github.com/KazKozDev/book-translator/blob/main/LICENSE"><img alt="License: AGPL-3.0-only" src="https://img.shields.io/badge/License-AGPL--3.0--only-blue.svg"></a>
  <a href="https://github.com/KazKozDev/book-translator/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/KazKozDev/book-translator/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://www.python.org/"><img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&amp;logoColor=white"></a>
</p>

<p align="center">
  <a href="https://github.com/KazKozDev/book-translator/issues">Issues</a> ·
  <a href="https://github.com/KazKozDev/book-translator/blob/main/CHANGELOG.md">Changelog</a> ·
  <a href="https://github.com/KazKozDev/book-translator/blob/main/CONTRIBUTING.md">Contributing</a> ·
  <a href="https://github.com/KazKozDev/book-translator/blob/main/LICENSE">LICENSE</a> ·
  <a href="https://github.com/KazKozDev/book-translator/blob/main/DISCLAIMER.md">DISCLAIMER</a> ·
  <a href="https://www.linkedin.com/in/kazkozdev/">LinkedIn</a>
</p>