docs(zh): improve translation prompt to avoid AI-style writing
Add a 'Writing style' section to the Chinese LLM translation prompt
that addresses common AI-generated translation patterns:
- Core rules: one sentence one idea, short sentences, spoken word order
- 12 concrete anti-patterns with real examples from current zh docs
- Reference style guides (Vue.js zh docs, 阮一峰, Go by Example zh)
- Expanded glossary from 4 to 22 terms (dependency injection, middleware,
validation, endpoint, decorator, etc.)
The current zh translations are grammatically correct but read like
AI output — overly formal, verbose, with English-influenced sentence
structure. This prompt improvement targets the root cause: the LLM
that generates the translations lacks style guidance.
@ -4,10 +4,57 @@ Translate to Simplified Chinese (简体中文).
Language code: zh.
### Writing style
Write like a developer explaining something to a colleague over lunch — clear, direct, slightly casual. The reader is a Chinese-speaking programmer, not a professor or a manager.
**Core rules:**
1. One sentence, one idea. If a sentence has "并且" or "同时" connecting two independent thoughts, split it.
2. Prefer short sentences (under 30 characters) over long ones.
3. Use spoken Chinese word order, not English-influenced structure.
4. Technical terms can stay in English if they're more commonly used that way (e.g. API, JSON, decorator, endpoint).
5. Don't hedge. If something is true, say it. Don't write "可能" or "或许" unless the original text genuinely expresses uncertainty.
**Patterns to avoid (AI-style Chinese):**
| ❌ Don't write | ✅ Write instead | Why |
|---|---|---|
| 将其复制到...文件中 | 复制到...里 | "将其" is literary, not spoken |
| 该行显示了...的URL地址 | 这行告诉你...的地址 | "该" as a pronoun is stiff; "地址" already implies URL |
| 你将会看到 | 你会看到 | "将会" is news-anchor tone |
| 它并非...而只是... | 不是...就是... | "并非...而只是" is essay-style |
- ❌ "你可以在...中找到..." → ✅ "在...里" or just state it directly
- ❌ "值得注意的是" → ✅ "注意" or just make the point
- ❌ "在这种情况下" → ✅ "这时" or "这种时候"
- ❌ "从...的角度来看" → ✅ Remove; just state the fact
- ❌ "对于...而言" → ✅ Remove; restructure the sentence
- ❌ "关于...的问题" → ✅ Remove; just name the topic
- ❌ Redundant "你的" (your) — English needs "your API", Chinese often drops it when context is clear
**Reference style:**
Think of how these write technical Chinese:
- Vue.js Chinese docs (vuejs.org/zh) — clean, direct, developer-friendly
- 阮一峰's blog — conversational but precise
- Go by Example Chinese (gobyexample-cn.github.io) — minimal, no fluff
### Grammar and tone
- Use clear, concise technical Chinese consistent with existing docs.
- Address the reader naturally (commonly using “你/你的”).
- Use "你" (not "您") to address the reader.
- Keep the tone helpful but not condescending. Don't over-explain things that are obvious to a developer.
- If the original English uses "you can..." or "you will see...", consider whether the Chinese version even needs the subject. Often you can drop "你" and just state the action.
### Headings
@ -17,12 +64,12 @@ Language code: zh.
### Quotes and punctuation
- Keep punctuation style consistent with existing Simplified Chinese docs (they often mix English terms like “FastAPI” with Chinese text).
- Keep punctuation style consistent with existing Simplified Chinese docs (they often mix English terms like "FastAPI" with Chinese text).
- Never change punctuation inside inline code, code blocks, URLs, or file paths.
### Ellipsis
- Keep ellipsis style consistent within each document, prefer `...` over `……`.
- Keep ellipsis style consistent within each document, prefer `...` over `……`.
- Never change ellipsis in code, URLs, or CLI examples.
### Preferred translations / glossary
@ -33,6 +80,28 @@ Use the following preferred translations when they apply in documentation prose:
GUOHAO LIU
3 weeks ago