Polish Mode

Polish mode refines existing text — fixing grammar, improving clarity, and making the writing sound natural — without translating it to another language. It’s especially useful for polishing text you’ve written in a language you’re still learning.

Basic usage

echo "Quiero hablar sobre el problema de deploy" | yaku --mode polish --to es

Output:

Quiero hablar sobre el problema del despliegue

The --to flag specifies which language the text should be polished in.

What polish mode does

• Fixes grammar, spelling, and punctuation
• Makes expressions natural for native speakers
• Preserves the original meaning and paragraph structure
• Returns the text with minimal changes if it is already well-written

What polish mode does not do

• Translate to a different language (use the default translate mode for that)
• Add information not in the original text
• Change the structure or merge/split paragraphs

Examples

Fix grammar in Spanish

echo "Yo quiero informarte que el deployment será retrasado por el problema que encontramos en testing." | \
  yaku --mode polish --to es

Output:

Quiero informarte que el despliegue se retrasará debido al problema que encontramos en las pruebas.

Fix grammar in French

echo "Je veux dire que le serveur est tombé hier et nous devons le fixer rapidement." | \
  yaku --mode polish --to fr

Output:

Je souhaite signaler que le serveur est tombé en panne hier et que nous devons le réparer rapidement.

Polish a file

yaku --mode polish --to es -f draft.md -o polished.md

For Markdown files, yaku preserves the structure (headings, code blocks, links) while polishing the prose.

Control tone with context

echo "El servidor se cayó otra vez ayer" | \
  yaku --mode polish --to es --context "formal incident report"

Output:

El servidor de producción experimentó una interrupción no planificada ayer.

echo "Necesito que alguien mire el bug del login" | \
  yaku --mode polish --to es --context "casual Slack message"

Output:

¿Alguien puede revisar el bug del login?

Polish Japanese text

Polish mode works for any language — useful when writing in a language you’re still learning:

echo "昨日のミーティングで話したことについてフォローアップしたいんだけど" | \
  yaku --mode polish --to ja --context "formal business email"

Output:

昨日の会議でお話しした件について、フォローアップさせていただきたく存じます。

Translate vs polish: when to use which

	--mode translate	--mode polish
Purpose	Convert text from one language to another	Improve text that’s already in the target language
Input language	Different from --to	Same as --to
--from flag	Supported (or auto-detect)	Ignored (warning shown)
--glossary	Supported	Ignored (warning shown)
--context	Guides domain terminology	Guides tone and formality

Common mistake: using polish on the wrong language

If the input text is in a different language than --to, always use translate mode:

# ✅ Correct: translate Japanese to English
echo "会議は明日の10時です" | yaku --to en

# ❌ Wrong: polishing Japanese text "in English" makes no sense
echo "会議は明日の10時です" | yaku --mode polish --to en

Polish mode tells the LLM “improve this text to sound natural in English” — but the input is Japanese. The LLM receives contradictory instructions and the result will be unreliable. Use translate mode when the input and target languages differ.

Use cases

• Writing in a second language — polish your Spanish, French, Japanese, or any language you’re still learning.
• Content editing — refine blog posts, README files, or user-facing text in any language.
• Tone adjustment — use --context to shift formality (see Context Hints).
• CI/CD quality checks — lint prose quality in pull requests.