{{ message }}
📝 Improve translation prompt to avoid AI-style writing in chinese docs#15711
Open
lennney wants to merge 8 commits into
Open
📝 Improve translation prompt to avoid AI-style writing in chinese docs#15711lennney wants to merge 8 commits into
lennney wants to merge 8 commits into
Conversation
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.
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Updates the Chinese (zh) LLM translation prompt to produce more natural, developer-oriented Simplified Chinese by adding detailed style guidance and expanding the glossary.
Changes:
- Added a “Writing style” section with concrete rules and anti-pattern examples for more natural Chinese.
- Refined grammar/tone guidance (use “你”, avoid over-explaining, often drop explicit subjects).
- Expanded the preferred translations / glossary with more common technical terms.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | 将其复制到...文件中 | 复制到...里 | "将其" is literary, not spoken | | ||
| | 该行显示了...的URL地址 | 这行告诉你...的地址 | "该" as a pronoun is stiff; "地址" already implies URL | | ||
| | 你将会看到 | 你会看到 | "将会" is news-anchor tone | | ||
| | 它并非...而只是... | 不是...就是... | "并非...而只是" is essay-style | |
Comment on lines
+21
to
+25
| | ❌ Don't write | ✅ Write instead | Why | | ||
| |---|---|---| | ||
| | 将其复制到...文件中 | 复制到...里 | "将其" is literary, not spoken | | ||
| | 该行显示了...的URL地址 | 这行告诉你...的地址 | "该" as a pronoun is stiff; "地址" already implies URL | | ||
| | 你将会看到 | 你会看到 | "将会" is news-anchor tone | |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 25f140371c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | 将其复制到...文件中 | 复制到...里 | "将其" is literary, not spoken | | ||
| | 该行显示了...的URL地址 | 这行告诉你...的地址 | "该" as a pronoun is stiff; "地址" already implies URL | | ||
| | 你将会看到 | 你会看到 | "将会" is news-anchor tone | | ||
| | 它并非...而只是... | 不是...就是... | "并非...而只是" is essay-style | |
There was a problem hiding this comment.
When the source means “not X, but only Y” (the exact case represented by 它并非...而只是...), the suggested replacement 不是...就是... changes the meaning to an either/or construction in Chinese. Because this prompt is used to generate future zh translations, that pattern can make the LLM drop the original negation and produce semantically incorrect docs instead of just less formal wording.
Useful? React with 👍 / 👎.
Contributor
📝 Docs previewLast commit 9df073a at: https://fcbf70b2.fastapitiangolo.pages.dev |
'不是...就是...' means 'either...or...' (disjunction), not the intended contrast. Changed to '不是...只是...' which preserves the original 'not X, but merely Y' meaning while still being more natural than '并非...而只是...'. Addresses Copilot and Codex review feedback.
Member
alejsdev
changed the title
Author
5 tasks
- Add terminology tiers (must-translate / keep-English / prose-only) - Add admonition type preservation rule (info ≠ note) - Add HTML attribute rules (alt text in Chinese) - Add W3C Chinese spacing rules - Add consistency rules (request body vs body) - Add core rules: preserve meaning, avoid slang - Expand anti-pattern table with new examples - Add new terms to glossary (body, form, file, etc.) Based on Vue.js translation guide, Microsoft style, and LLM prompt engineering best practices.
…i-patterns Round 2 improvements based on PR fastapi#15717 analysis (18 violations found): - Fix Tier 1/Tier 2 contradiction: decorator, endpoint moved to Tier 3 - Add core rule 9: 其他 not 其它 - Add core rule 10: no repeated conjunctions 并...并 - Add anchor ID rule (never translate {#...}) - Add code block rule (no translation inside code/comments) - Add more anti-patterns: 另一个→另一套, 模型对象的→模型的 - Add redundant 你的 examples with specific fixes - Extend Tier 2 with tools (VS Code, PyCharm, Celery, etc.) - Clarify Body class vs body concept distinction - Add cross-document consistency rule
- Add rule 11: Tier 3 terms in prose must be translated even if Python keywords - Add rule 12: omit 会 for deterministic behavior - Add terminology teaching section (first occurrence English + annotation) - Add pre-translation scan rule (check existing files for consistency) 3 rounds of iteration: 18 → 17 → 0 new rule gaps identified.
Align with Chinese Python community convention where type annotations are called 类型注解, not 类型标注.
- Add terminology glossary (71+ terms) with NOT alternatives - Add anti-patterns table (16 rules for natural Chinese) - Add good translation examples (7 side-by-side comparisons) - Add post-translation review checklist - Add spacing rules for Chinese-English formatting - Categories: FastAPI core (23), Web (14), Python (24), Dev tools (10) - Keep-English list: frameworks, protocols, abbreviations, class names - Based on analysis of existing translations and PR fastapi#15717
This comment was marked as resolved.
This comment was marked as resolved.
- Remove 'Post-translation review' (not applicable to chat completions) - Remove 'Code blocks' section (already in general prompt) - Remove 'HTML attributes' section (general prompt has abbr/dfn rules) - Remove 'Anchor IDs' from Headings (already in general prompt) - Add notes that Headings and Admonitions supplement the general prompt Addresses feedback from @YuriiMotov on PR fastapi#15711.
This comment was marked as resolved.
This comment was marked as resolved.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Improve
docs/zh/llm-prompt.md— the prompt that drives LLM-generated Chinese translations — to eliminate common AI-style writing patterns.Problem
The current Chinese translations are grammatically correct but read like AI output: overly formal, verbose, with English-influenced sentence structure. Examples from the live docs:
The root cause: the translation prompt has glossary and formatting rules, but zero guidance on writing style.
Changes
Added a "Writing style" section to
docs/zh/llm-prompt.md:Also refined "Grammar and tone" to explicitly state "用'你'不用'您'" and add guidance on dropping unnecessary subjects.
Total: 1 file changed, +73/-4 lines.
Why this approach
FastAPI's contributing guide says the best way to improve zh translations is to improve the LLM prompt — this changes the source, not the symptoms.