Why yaku?

yaku is a CLI tool that translates text, files, and structured documents from your terminal. Install it, run yaku --to en "你好", and get a translation — no API key, no account, no configuration needed.

Under the hood, yaku is designed to handle real-world files: it translates Markdown without breaking formatting, translates JSON and YAML values while keeping keys intact, and lets you enforce terminology with glossary files. It reads from stdin, files, or arguments and writes to stdout, so it fits naturally into scripts and pipelines.

This page helps you decide if yaku is the right tool for your needs.

What yaku does

Translate text between languages — any language pair your LLM backend supports.
Polish writing — refine grammar and fluency in text you’ve written in a non-native language, without translating it.
Preserve structure — translate Markdown, JSON, and YAML without breaking formatting. Keys, code blocks, URLs, and front matter stay untouched.
Control terminology — glossary files lock down translations of specific terms or keep them untranslated.
Fit into pipelines — stdin/stdout by default, composable with curl, gh, git, jq, and any other CLI tool.

What yaku does not do

yaku’s scope is helping you cross language barriers. Features outside this scope are intentionally excluded:

Not in scope	Use instead
Code generation or explanation	General-purpose AI CLIs (`llm`, `aichat`, `sgpt`)
Text summarization	General-purpose AI CLIs
Question answering or chat	ChatGPT, Claude, or general-purpose AI CLIs
Format conversion (e.g., Markdown → HTML)	`pandoc`
Spell checking without translation context	`aspell`, `languagetool`
GUI-based translation	Google Translate, DeepL

Rule of thumb: if a task doesn’t involve crossing a language barrier, yaku is not the right tool.

How yaku compares

vs. Google Translate / DeepL / ChatGPT

These are browser-based tools. You leave your terminal, copy text, paste it, get the result, and paste it back. yaku eliminates this context switch:

# Instead of copy-pasting to a browser:
echo "Bonjour, comment ça va ?" | yaku --to en
cat error.log | yaku --to en --context "nginx error log"
yaku --to en -f README.ja.md -o README.md

yaku also preserves file structure (JSON keys, Markdown formatting) and supports glossary-based terminology control — features browser tools don’t offer.

vs. general-purpose AI CLIs (`llm`, `sgpt`, `aichat`)

These tools send arbitrary prompts to LLMs. You can translate with them, but you write the prompt yourself every time:

# With a general-purpose AI CLI:
echo "Bonjour" | llm "translate this to English"

# With yaku:
echo "Bonjour" | yaku --to en

The difference:

	yaku	General-purpose AI CLIs
Prompt engineering	Built-in, tuned for translation quality	You write your own prompt
Format preservation	Automatic for Markdown, JSON, YAML	Manual (hope the LLM follows your instructions)
Glossary support	Built-in (`.yaku-glossary.yaml`)	Not available
Output cleanliness	Sanitized — no “Here is the translation:” preambles	Raw LLM output
Scope	Translation and polishing only	Anything you can prompt

If you need a Swiss Army knife for all AI tasks, use llm or aichat. If you want reliable, structured translations with consistent terminology, use yaku.

vs. Translate Shell (`trans`)

Translate Shell uses traditional translation engines (Google, Bing), not LLMs. It’s fast and free, but:

No format awareness — cannot translate JSON/YAML while preserving keys
No glossary or terminology control
Translation quality limited by the underlying engine (often literal, less natural)
No polish mode

Translate Shell is a good fit for quick lookups. yaku is better for developer artifacts, structured files, and quality-sensitive translations.

When to use yaku

You translate developer artifacts (docs, i18n files, README, error messages) regularly.
You want consistent terminology across a project (glossary).
You work with structured files (Markdown, JSON, YAML) and need the structure preserved.
You write in a non-native language and want to polish your text.
You want translation as part of a script or CI/CD pipeline.

When not to use yaku

You need a general-purpose AI assistant — yaku only translates and polishes. Use llm, aichat, or sgpt for code generation, summarization, or Q&A.
You need real-time interactive conversation — yaku is stateless (one input, one output). Use ChatGPT or Claude for back-and-forth dialogue.
You need fully offline translation without any setup — yaku requires either internet access (hosted backend) or a local LLM running (e.g., Ollama). It doesn’t bundle a model.
You need GUI-based translation — yaku is terminal-only. Use Google Translate or DeepL for browser-based workflows.