translate-docs

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.