/translate-docs

name: translate-docs
description: Translate VMark documentation and app strings to all 9 supported locales with subagent-driven audit, proofreading, and cultural polish. Use when adding or updating website pages, React locale JSON (src/locales/en/*.json), or Rust locale YAML (src-tauri/locales/en.yml) that need multi-language support.

VMark Translation

Two modes share the same 9 locales, the same subagent pipeline, and the same cultural rules:

• **Docs mode** (default) — translate `website/guide/**/*.md` markdown files.
• **App string mode** (`--app`) — sync new keys across `src/locales/{locale}/*.json` (i18next) and `src-tauri/locales/{locale}.yml` (rust-i18n).

Docs mode is the original flow; App string mode was added to handle the smaller, structured strings that the app ships every day. They share Stages 2–4 (translate → audit → cultural polish) but differ in what they read, what they write, and how they protect existing content.

When to Use

Docs mode

• Adding a new page to `website/guide/`
• Updating an existing page that needs translation sync
• User asks to "translate", "localize", or "add language support" for website content

App string mode (`--app`)

• New keys appear in `src/locales/en/*.json` or `src-tauri/locales/en.yml` without matching entries in other locales
• `pnpm lint:i18n` reports missing keys
• User asks to "sync locale files", "translate new i18n keys", or "propagate locale keys"

Target Locales

| Code | Language | CJK? | |------|----------|------| | `zh-CN` | Simplified Chinese | Yes | | `zh-TW` | Traditional Chinese | Yes | | `ja` | Japanese | Yes | | `ko` | Korean | Yes | | `de` | German | No | | `fr` | French | No | | `es` | Spanish | No | | `it` | Italian | No | | `pt-BR` | Brazilian Portuguese | No |

Workflow

Step 1: Prepare Source

1. Read the English source file from `website/guide/...` 2. Identify the file path pattern (e.g., `guide/users-as-developers/foo.md`) 3. Check that all target locale directories exist: `website/{locale}/guide/...`

Step 2: Translate (parallel subagents)

Dispatch **up to 9 translation subagents in parallel** — one per locale. Each subagent receives:

• The full English source content
• The target locale code and language name
• Translation rules (see below)

**Translation Rules for Every Locale:**

1. **Translate all prose** — headings, paragraphs, list items, block quotes, alert blocks 2. **Preserve markdown structure exactly** — headings levels, link URLs, code blocks, tables, images, front matter 3. **Keep technical terms in English** — product names (VMark, Tauri, ProseMirror, Tiptap, CodeMirror, Mermaid, Vitest), programming terms in code context (LOC, TDD, CI/CD, API, MCP), file paths, command names 4. **Translate table headers and cell text** — but keep code/numbers as-is 5. **Translate VitePress containers** — `::: info`, `::: tip`, `::: warning` labels stay as-is (VitePress renders them), but translate the content inside 6. **Adapt culturally** — don't just word-swap. Use natural phrasing. Examples:

• "TL;DR" → "太长不看版" (zh-CN), "要約" (ja), "요약" (ko)
• "out of the box" → use the local idiom, not a literal translation
• Currency/number formatting: use locale conventions in prose (but keep raw numbers in tables/code)

7. **Em-dash spacing** — follow VMark convention: `word — word` with spaces in English/European locales. CJK locales use `——` (double em-dash) without spaces.

**Additional CJK Rules (zh-CN, zh-TW, ja, ko):**

8. **CJK-Latin spacing** — Always insert a space between CJK characters and Latin letters/numbers: `学习 Python 编程` not `学习Python编程` 9. **Fullwidth punctuation** — Use fullwidth comma `，`, period `。`, colon `：`, question mark `？`, exclamation `！` in CJK prose. Keep halfwidth in code/URLs. 10. **No space before fullwidth punctuation** — `你好，世界` not `你好 ，世界` 11. **zh-TW specifics** — Use Traditional Chinese characters. Use `「」` for quotes instead of `""`. Use Taiwanese terminology where it differs from mainland (e.g., 程式 not 程序, 資料 not 数据). 12. **ja specifics** — Use appropriate kanji/hiragana/katakana mix. Technical terms typically use katakana (エディタ, ファイル). Use `「」` for quotes. 13. **ko specifics** — Use Hangul for Korean words, keep English for technical terms. Use `「」` or `""` for quotes.

Step 3: Audit & Proofread (parallel subagents)

After all translations are written, dispatch **audit subagents in parallel** — one per locale. Each subagent:

1. **Reads both** the English source AND the translated output 2. **Checks for:**

• Missing or extra paragraphs/sections (structural drift)
• Untranslated fragments left behind
• Meaning drift or mistranslation
• Broken markdown (unclosed links, malformed tables, wrong heading levels)
• Links that should point to the locale version (e.g., `/guide/foo` → `/{locale}/guide/foo` if the site uses locale-prefixed links — note: VMark VitePress does NOT prefix internal links, so keep them as-is)
• Grammar and fluency issues
• CJK formatting violations (for CJK locales):
• Missing spaces between CJK and Latin/numbers
• Halfwidth punctuation in CJK prose
• Spaces before fullwidth punctuation

3. **Outputs a verdict:**

• `PASS` — no issues found
• `FIX: [list of issues with line numbers]` — issues that need correction

If any locale gets `FIX`, apply corrections and re-run that locale's audit (max 2 retries).

Step 4: Cultural Polish (parallel subagents, CJK only)

For CJK locales only (zh-CN, zh-TW, ja, ko), dispatch a **cultural polish subagent** that:

1. Reads the audited translation 2. Checks for "translationese" — phrasing that's grammatically correct but sounds like a translation rather than native writing 3. Adapts idioms and cultural references 4. Verifies register/tone matches the target audience (technical but approachable) 5. For zh-CN/zh-TW: ensures the text reads as natural Chinese, not English-shaped Chinese 6. For ja: ensures proper keigo level (polite but not