Translator is a CLI tool that takes a text file and a target language, then runs the content through up to four AI passes — initial translation, expert editing, critique, and revision — to produce output that reads like it was written natively. It handles markdown frontmatter (Hugo, Jekyll) without mangling your metadata.

Install

uv tool install git+https://github.com/2389-research/translator

Then:

translator input.txt Spanish

This creates input.es.txt in the same directory.

What it does

Multi-stage translation pipeline. The default flow runs four passes: raw translation, an editing pass for natural phrasing, a critique that flags issues, and a revision that addresses the critique. You can skip the edit (--no-edit) or critique (--no-critique) stages, or set 1–5 critique loops with --critique-loops.

Markdown frontmatter preservation. Files with YAML frontmatter get their metadata extracted before translation and reattached after. Your date, tags, slug, and other fields stay intact.

Multi-provider AI. Supports both OpenAI and Anthropic models. Prefix a model name to pick the provider explicitly (openai:gpt-4o, anthropic:claude-sonnet-4) or let it auto-detect. Defaults to claude-opus-4.1.

Cost estimation before you commit. Run --estimate-only to see token counts and estimated cost before spending API credits. Real-time token tracking reports actual usage after each run.

Streaming terminal UI. Translation streams to your terminal in real time via Rich, so you can watch progress on long documents instead of staring at a spinner.

Any language OpenAI or Anthropic supports. Pass a language name (“Japanese”, “Portuguese”, “Korean”) and translator maps it to the correct ISO 639-1 code for output filenames automatically.

How it works

The CLI reads your file, extracts any frontmatter, counts tokens against the selected model’s limits, and estimates cost. Then it sends the content through the translation pipeline — each stage uses purpose-built prompts stored in prompts.py. The whole process gets logged as structured JSON, and a narrative summary is generated from the logs after completion.

Requirements

Python 3.13+
An API key for at least one provider: OPENAI_API_KEY or ANTHROPIC_API_KEY
Run translator config for interactive setup