Tinbox

Translate documents from your terminal with cloud or local language models.

Tinbox reads PDFs, Word documents, and text files, then writes translations as text, JSON, or Markdown reports. It splits long text into chunks, can carry context and glossary terms between requests, and saves progress when you enable checkpoints.

Quick start · Providers · Workflows · CLI reference · Translation review · Contributing

Quick start

This example translates a short English note into German with GPT-6.1 Sol. Install uv and have an OpenAI API key ready. Tinbox requires Python 3.12 or newer.

Install Tinbox 0.3.0 or newer with OpenAI support:

uv tool install --python 3.13 "tinbox[openai]>=0.3.0"

Set your key, create a sample file, and translate it. These examples use a Bash or Zsh shell and the default OpenAI endpoint; unset OPENAI_BASE_URL if you previously configured another server.

export OPENAI_API_KEY="your-openai-api-key"
printf 'The library opens at nine.\n' > note.txt

tinbox translate note.txt --from en --to de \
  --model openai:gpt-6.1-sol --output note.de.txt

cat note.de.txt

Tinbox shows a translation plan, progress, and statistics in the terminal. note.de.txt contains only the translated text, for example:

Die Bibliothek öffnet um neun.

The wording can vary. Translation calls your provider and may incur API charges. To inspect the plan without contacting a model, add --dry-run to the translation command; it will not create an output file.

Prefer a local model? Use Gemma 4 with Ollama, or see provider setup for Claude, Gemini, and custom endpoints. The guide also covers installation from PyPI and upgrades.

What can I translate?

All inputs produce text, JSON, or a Markdown report. Tinbox does not export translated PDF or Word files. Translation quality and language coverage depend on the model; the CLI accepts a defined set of language codes.

Common tasks

Review a text translation

For a fresh context-aware .txt translation, preserve the source and translation chunks and render an offline report:

tinbox translate document.txt --from en --to de --model openai:gpt-6.1-sol \
  --output document.de.txt --save-review-input document.de.review.json

tinbox review document.de.review.json --output document.de.review.html

The translation review guide explains how to curate sentence matches, leave ambiguous regions unchecked, and optionally send matched groups to TypeSafe for participant, certainty, and quantifier checks. Reports preserve the translated text; matching and TypeSafe hints do not certify its quality. Only the explicit annotate-review command sends text to TypeSafe. Review files contain document text and require new output paths.

TranslateGemma with oMLX

For a local TranslateGemma server, use the dedicated TranslateGemma setup. It supports short text files with an explicit source language; it does not support PDFs, glossaries, or context-aware chunking.

Limits worth knowing

• Costs are approximate. Tinbox uses fixed provider rates, not live model prices. --max-cost checks recorded cost after requests complete and is not a billing cap.
• Model compatibility varies. The provider guide lists current examples and request settings. A dry run checks local options and estimates, not provider access or translation quality.
• Check results before relying on them. A PDF translation can contain failed pages. JSON and Markdown reports include error details; see output formats.

Help and development

tinbox --help
tinbox translate --help
tinbox doctor

Read the CLI reference, setup troubleshooting, or contributing guide. For release and upgrade notes, see the changelog.

Licensed under the MIT License.