Format-Aware Translation

yaku detects the input format and adjusts its translation strategy to preserve structure. Keys, code blocks, URLs, and other non-translatable elements stay untouched.

Format detection

yaku determines the format in this order:

1. --format flag — explicit override: --format json
2. File extension from -f — .md, .json, .yaml, .yml
3. Default — plain text

Extension	Detected format
.md, .markdown, .mdx	Markdown
.json	JSON
.yaml, .yml	YAML
Everything else	Text

Markdown

yaku sends the full Markdown document to the LLM with extra rules to preserve structure:

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

What gets translated:

• Paragraph text
• Heading text
• List item text
• Link display text (e.g., [this part](url))
• Blockquote text

What stays untouched:

• Heading markers (#, ##, ###)
• Code blocks (fenced and indented)
• Inline code (backticks)
• Link URLs and image paths
• Front matter (--- ... ---)
• HTML tags
• List and blockquote markers
• File paths, URLs, and email addresses

Example

Input (README.fr.md):

# Démarrage rapide

Installez le paquet :

```bash
npm install my-package
```

Consultez la [documentation](https://example.com) pour plus de détails.

yaku --to en -f README.fr.md

Output:

# Quick Start

Install the package:

```bash
npm install my-package
```

See the [documentation](https://example.com) for more details.

Notice: heading markers, code block, and URL are preserved. Only the prose is translated.

JSON

yaku extracts all string values, translates them as a batch, and reassembles the JSON with the original structure:

yaku --to en -f zh-TW.json -o en.json

What gets translated:

• String values

What stays untouched:

• All keys
• Numbers, booleans, nulls
• Nesting structure
• Array ordering

Example

Input (ja.json):

{
  "nav": {
    "home": "ホーム",
    "about": "会社概要",
    "contact": "お問い合わせ"
  },
  "hero": {
    "title": "素晴らしいものを作ろう",
    "subtitle": "製品を最速で届ける方法",
    "cta": "始める"
  },
  "footer": {
    "copyright": "全著作権所有",
    "version": 2
  }
}

yaku --to en -f ja.json -o en.json

Output (en.json):

{
  "nav": {
    "home": "Home",
    "about": "About Us",
    "contact": "Contact"
  },
  "hero": {
    "title": "Build something great",
    "subtitle": "The fastest way to ship your product",
    "cta": "Get Started"
  },
  "footer": {
    "copyright": "All rights reserved",
    "version": 2
  }
}

Keys, structure, and the numeric version field are preserved exactly.

YAML

Works the same as JSON — string values are extracted, translated, and reassembled:

yaku --to en -f ja.yaml -o en.yaml

Example

Input (fr.yaml):

app:
  name: Mon Application
  description: Un outil de gestion des tâches

messages:
  welcome: Bon retour !
  error: Une erreur est survenue
  confirm: Êtes-vous sûr ?

settings:
  max_retries: 3
  debug: false

yaku --to en -f fr.yaml -o en.yaml

Output (en.yaml):

app:
  name: My Application
  description: A task management tool

messages:
  welcome: Welcome back!
  error: Something went wrong
  confirm: Are you sure?

settings:
  max_retries: 3
  debug: false

Keys, integers, and booleans are preserved. Only string values are translated — including short single-word values like "dark" or "urgent". Code identifiers (camelCase, snake_case, ALL_CAPS) and locale codes (e.g., "en", "zh-TW") are kept as-is.

Plain text

The default format. The entire input is sent to the LLM as-is:

echo "Bonjour le monde" | yaku --to en
yaku --to en "おはようございます"

No structural analysis is performed. Use this for short text, paragraphs, or any unstructured content.

Forcing a format

Override auto-detection with --format:

# Treat stdin as Markdown even though there is no file extension
cat doc.txt | yaku --to en --format md

# Treat a .txt file as YAML
yaku --to en -f data.txt --format yaml