Recipe: Translate a README

This recipe walks through translating a Markdown README into another language, keeping all structural elements intact.

Basic approach

yaku --to zh-TW -f README.md -o README.zh-TW.md

yaku detects the .md extension and applies Markdown-aware translation: headings, code blocks, links, images, and front matter stay untouched. Only the prose is translated.

Step-by-step walkthrough

1. Set up a glossary (optional but recommended)

Create .yaku-glossary.yaml in your project root to lock down key terms:

zh-TW:
  MyProject: ~           # keep project name
  GitHub: ~
  npm: ~
  MIT License: MIT 授權條款

2. Translate

yaku --to zh-TW -f README.md -o README.zh-TW.md

3. Review the output

Check a few things:

• Are headings at the correct level?
• Are code blocks unchanged?
• Are link URLs and image paths intact?
• Does the glossary terminology look correct?

4. Translate to additional languages

yaku --to ja -f README.md -o README.ja.md
yaku --to ko -f README.md -o README.ko.md

Adding context for better quality

If your README covers a specific domain, add context:

yaku --to zh-TW \
  --context "CLI developer tool documentation" \
  -f README.md -o README.zh-TW.md

Automating with a script

Translate your README into multiple languages:

#!/bin/bash
LANGUAGES=("zh-TW" "ja" "ko" "fr" "de")

for lang in "${LANGUAGES[@]}"; do
  yaku --to "$lang" -f README.md -o "README.${lang}.md"
  echo "Translated to $lang"
done

Tips

• Always review the output. LLM translation is good but not perfect. Review brand names, technical terms, and idiomatic expressions.
• Use a glossary for consistency. If you retranslate after updating the README, a glossary ensures the same terms are used every time.
• Translate from the source file. Always translate from the English (or original language) README, not from another translated version — this avoids compounding errors.