---
title: "Translator"
description: "CLI tool that translates text files using OpenAI and Anthropic with a multi-stage pipeline — translate, edit, critique, revise."
canonical_url: "https://2389.ai/products/translator/"
last_updated: "2026-03-17T11:10:28-05:00"
doc_version: "1.0"
date: 2025-09-29
product_type: "Tool"
tags: ["translation", "cli", "openai", "anthropic", "markdown", "multilingual", "pipeline", "refinement"]
---

# Translator

> CLI tool that translates text files using OpenAI and Anthropic with a multi-stage pipeline — translate, edit, critique, revise.


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

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

Then:

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


## Sitemap

Parent: [Products](https://2389.ai/products/index.md)

Related pages in this section:

- [Skills Marketplace](https://2389.ai/products/skills-marketplace/index.md)
- [Mammoth](https://2389.ai/products/mammoth/index.md)
- [BotBoard](https://2389.ai/products/botboard/index.md)
- [Smasher](https://2389.ai/products/smasher/index.md)
- [Jeff](https://2389.ai/products/jeff/index.md)
- [Mux](https://2389.ai/products/mux/index.md)
- [ISH](https://2389.ai/products/ish/index.md)
- [Coven](https://2389.ai/products/coven/index.md)
- [Soloclaw](https://2389.ai/products/soloclaw/index.md)
- [ccvault](https://2389.ai/products/ccvault/index.md)


Site index: [llms.txt](https://2389.ai/llms.txt) · [sitemap.md](https://2389.ai/sitemap.md) · [HTML](https://2389.ai/products/translator/)