Rewrite documentation with localization-aware style for a specified audience. MUST use when the user mentions any of these actions on a document: 重写/改写/润色/本土化/翻译/转写/rewrite/rephrase/localize/translate/polish/adapt. Also trigger when user says "写成中文/英文", "用中文重新写", "make this more natural", "这个文档读起来像翻译", "帮我改成面向XX的", or provides a doc asking for better wording, tone adjustment, or audience adaptation. Covers: markdown docs, specs, READMEs, design docs, product docs, guides, changelogs.
Rewrite documentation with localization-aware style for a specified audience. MUST use when the user mentions any of these actions on a document: 重写/改写/润色/本土化/翻译/转写/rewrite/rephrase/localize/translate/polish/adapt. Also trigger when user says "写成中文/英文", "用中文重新写", "make this more natural", "这个文档读起来像翻译", "帮我改成面向XX的", or provides a doc asking for better wording, tone adjustment, or audience adaptation. Covers: markdown docs, specs, READMEs, design docs, product docs, guides, changelogs.
Rewrite Doc
Rewrite documentation for a target audience while preserving technical precision.
When to Use
User asks to rewrite, localize, or rephrase a document
User provides a doc and specifies an audience or language preference
User says the doc "reads like a translation" or needs better flow
Workflow
1. Identify Parameters
Before rewriting, determine:
Parameter
How to resolve
Output language
User-specified > auto-detect from user's input language
Audience
Ask if not obvious (e.g., senior engineers, junior devs, PMs, end users)
Register
Technical docs default to formal-concise; READMEs default to approachable
If the user doesn't specify language, match the language they're writing in.
2. Rewriting Principles
Structure:
Headings use domain terminology in the lingua franca of the field (usually English for tech). This makes headings scannable and grep-friendly.
Body text uses the target language natively, not translated. Write as a native speaker of that language would write for peers.
Terminology:
Preserve technical terms in their canonical form (OKLCH, shadcn, RBAC, SSR, monorepo, CRUD, etc.)
Do not translate proper nouns, library names, CLI commands, or code identifiers
When a term has both a native word and an English loanword equally understood by the audience, prefer the one that reads more naturally in context
Tone calibration by audience:
Audience
Characteristics
Senior engineers
Dense, assumes context, no hand-holding. Skip obvious explanations.
Junior engineers
More connective tissue, brief clarifications for non-obvious concepts.
PMs / non-technical
Explain the "what" and "why", skip the "how" implementation details.
End users
Task-oriented, no jargon, action-first.
Anti-patterns to eliminate:
Machine-translation artifacts ("进行操作" → just use the verb directly)
Unnecessary filler ("需要注意的是", "值得一提的是")
Passive voice where active is more direct
Restating what the heading already says in the first sentence
Em dashes (use commas, colons, semicolons, or parentheses instead)
3. Execute
Read the source document in full
Identify sections that are purely structural (tables, code blocks, YAML) vs. prose
Rewrite prose sections applying the principles above
Preserve code blocks, YAML frontmatter, and table data verbatim (only rewrite human-readable labels/descriptions within them)
Output the complete rewritten document
4. Self-check
After rewriting, verify:
No heading is a literal translation of a Chinese/English phrase when the domain term exists
No sentence starts with the same word as the heading above it
Technical terms are consistent throughout (don't alternate between translations)
The document flows naturally when read aloud in the target language
