wordbridge

Local-first markdown translation tool. Runs entirely on your machine — no cloud APIs, no data leaving your system.

Modes

Mode	What it does
ame-bre	American → British English spelling (dictionary-based, no GPU)
en-de	English → German via Ollama (requires a local LLM)
both	Both translations in one pass, written to separate output files

Markdown structure is preserved: headings, code blocks, inline code, lists, and tables pass through untouched. Only prose segments are translated.

---

Requirements

• Python 3.11+
• Ollama running locally (for en-de / both modes)
• Model: qwen3:32b-q4_K_M (default — change in config.toml if needed)

AMD GPU note: If you have multiple ROCm devices (e.g. discrete + integrated graphics), set rocr_visible_devices = "0" in config.toml or run with ROCR_VISIBLE_DEVICES=0 to avoid Ollama crashing on the wrong device.

---

Installation

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e .

# Pull the model (once)
wordbridge ollama pull

---

Usage

Interactive (guided)

wordbridge run

Prompts for input path, mode, and output location. The easiest way to get started.

Single file

wordbridge translate document.md --mode en-de
wordbridge translate document.md --mode ame-bre --diff
wordbridge translate document.md --mode both --output-dir ./out

Output goes to ./output/<stem>_bre.md or ./output/<stem>_de.md by default. --diff prints a word-level diff to the terminal after the AmE→BrE pass.

Directory (batch)

wordbridge translate ./docs/ --mode en-de --output-dir ./docs-de

Recursively finds *.md and *.txt files, writes results to --output-dir preserving the directory structure.

Stdin / stdout

cat file.md | wordbridge translate - --mode ame-bre

Ollama helpers

wordbridge ollama status    # check if Ollama is reachable and which models are loaded
wordbridge ollama pull      # pull the configured model

With Makefile

make install        # pip install -e .
make dev            # pip install -e ".[dev]"
make run            # wordbridge run (interactive)
make run-en-de      # quick translate on tests/fixtures/sample_en.md
make run-ame-bre
make run-both
make test           # pytest
make lint           # ruff check
make typecheck      # mypy

---

Configuration

wordbridge works with defaults out of the box. To override, create config.toml in the project root (or ~/.config/wordbridge/config.toml):

[ollama]
model = "qwen3:32b-q4_K_M"
rocr_visible_devices = "0"   # AMD multi-GPU systems only

[translation.en_de]
batch_token_limit = 800      # tokens per LLM request
no_think = true              # disable chain-of-thought (faster, less VRAM)
retry_attempts = 1

[qa]
log_level = "info"           # "debug" streams LLM tokens to terminal

The included config.toml lists every option with its default commented out.

---

QA commands

After a translation run, two artefacts are written to the output directory:

wordbridge qa log      # show the full structured run log
wordbridge qa delta    # segment length ratio report (flags suspiciously short/long translations)
wordbridge qa delta --warn-only   # only show segments with warnings

---

Development

pip install -e ".[dev]"
pytest -q
mypy wordbridge/
ruff check wordbridge/ tests/