docs: add Chinese documentation translation#1795
docs: add Chinese documentation translation#1795cccczl wants to merge 1 commit intobmad-code-org:mainfrom
Conversation
📝 WalkthroughWalkthroughThis PR adds comprehensive Chinese localization for the BMad Method project, introducing a translated README_CN.md and 20+ Chinese documentation files (README_CN.md, docs_cn/* structure) covering style guides, tutorials, how-to guides, explanations, references, roadmap, and index pages. Approximately 2,700+ lines of Chinese documentation content with no code changes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~45 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Note
Due to the large number of review comments, Critical severity comments were prioritized as inline comments.
🟠 Major comments (33)
docs_cn/how-to/customize-bmad_cn.md-96-127 (1)
96-127:⚠️ Potential issue | 🟠 MajorAdd security warnings for custom workflows and prompts.
Lines 96-127 describe adding custom workflows and prompts without any security warnings. This is a critical omission because:
Security risks not mentioned:
- Custom workflows (line 99) can execute arbitrary code on the user's system
- Malicious workflows could exfiltrate data, modify files, or compromise credentials
- Prompt injection (lines 122-126) could be exploited if content comes from untrusted sources
- No guidance on validating workflow sources or sandboxing execution
Users need explicit warnings about:
- Only using workflows from trusted sources
- Reviewing workflow code before adding to customize.yaml
- Understanding that these workflows run with full system privileges
- Keeping customize.yaml files out of version control if they contain sensitive data
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/customize-bmad_cn.md` around lines 96 - 127, Add explicit security warnings to the section showing custom workflows and prompts: update the text around the YAML examples (the menu with trigger: my-workflow / deploy, the critical_actions block, and the prompts block with id: deploy-prompt) to warn users that custom workflows can execute arbitrary code, may run with full system privileges, and can exfiltrate or modify data; instruct readers to only use workflows from trusted sources, to review workflow files before adding them to customize.yaml, to sandbox or run with least privilege when possible, and to avoid committing customize.yaml containing secrets to version control.docs_cn/how-to/customize-bmad_cn.md-141-141 (1)
141-141:⚠️ Potential issue | 🟠 MajorAdd warning about automatic updates to latest versions.
Line 141 states that "Quick Update" updates ALL modules to the latest version. This could introduce breaking changes or incompatibilities without user consent. The documentation should warn users that:
- Latest versions may contain breaking changes
- No rollback mechanism is documented
- Users should review changelogs before choosing this option
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/customize-bmad_cn.md` at line 141, Add a clear warning near the "Quick Update" table row that explains automatic updates will pull ALL modules to the latest versions and may introduce breaking changes, that there is no documented rollback mechanism, and that users should review changelogs and test before using this option; update the "Quick Update" entry or add a note immediately adjacent to it (referencing the "Quick Update" table row) containing those three bullet points as a cautionary notice.docs_cn/how-to/customize-bmad_cn.md-147-164 (1)
147-164:⚠️ Potential issue | 🟠 MajorAdd validation and backup procedures to troubleshooting.
The troubleshooting section is reactive but lacks preventive measures:
Missing critical procedures:
- Pre-validation: How to check YAML syntax BEFORE running install (e.g., using
yamllintor online validators)- Backup: How to save current working configuration before making changes
- Diff/preview: How to see what will change without applying it
- Specific errors: Common error messages and their solutions (e.g., "invalid yaml syntax at line X")
Users will make mistakes in YAML syntax and need these tools before breaking their setup.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/customize-bmad_cn.md` around lines 147 - 164, Extend the "故障排除" section to add proactive validation and backup steps: under the existing troubleshooting headings (e.g., "更改未生效？" and "需要重置智能体？") add a "预防措施" or "变更前检查" subsection that explains how to pre-validate YAML (suggest commands/tools like yamllint and online validators), how to create a backup of the current .customize.yaml ( advise copying/renaming the file before edits), how to preview/diff changes (suggest using git diff or simple file diff tools before running npx bmad-method install), and list a few common error messages (e.g., "invalid yaml syntax at line X") with brief remedies; ensure references to the existing command `npx bmad-method install` and the `.customize.yaml` filename remain consistent so users can follow the new preventive workflow.docs_cn/how-to/customize-bmad_cn.md-86-90 (1)
86-90:⚠️ Potential issue | 🟠 MajorWarn against storing sensitive data in memories.
The memories section allows storing persistent context but lacks critical warnings:
Data handling concerns:
- Memories are likely logged or stored in plain text
- No indication of encryption or security
- Users might accidentally store API keys, passwords, or PII
- No mention of GDPR/privacy implications
- No guidance on memory retention or cleanup
Add explicit warnings:
- "
⚠️ Do not store sensitive data, credentials, or PII in memories"- "Memories may be logged and are not encrypted"
- Link to secure credential management documentation
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/customize-bmad_cn.md` around lines 86 - 90, The docs' memories example (the "memories" YAML block and its example entries) lacks any security/privacy guidance; update the "memories" section to add a clear warning paragraph stating: "⚠️ Do not store sensitive data, credentials, or PII in memories. Memories may be logged and are not encrypted." Also add brief guidance about retention/cleanup (how long memories persist and how to delete them), a GDPR/privacy note, and a link to the project's secure credential management documentation (add an inline hyperlink or reference to the secure-credentials guide) so readers know where to store secrets safely.docs_cn/explanation/project-context_cn.md-8-8 (1)
8-8:⚠️ Potential issue | 🟠 MajorRepeated broken self-references to
project-context.mdThese links use
(project-context.md)from withindocs_cn/explanation/, which likely resolves to a non-existent doc path. If you intended to reference the artifact file in user projects, render it as code text (not a hyperlink). If you intended a doc page, point to the actual Chinese doc route.Also applies to: 17-17, 21-21, 33-33, 130-130, 146-146
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/explanation/project-context_cn.md` at line 8, The markdown in docs_cn/explanation/project-context_cn.md contains broken self-references using the hyperlink text `(project-context.md)`; locate all occurrences of the literal "project-context.md" in this file (also the other occurrences noted) and either replace the hyperlink with inline code formatting (`project-context.md`) when you mean to reference the artifact file, or update the link target to the correct Chinese doc route (e.g., the actual translated page URL) if you meant to link a doc page; ensure the displayed text and link target are consistent for each replacement.docs_cn/how-to/quick-fixes_cn.md-71-79 (1)
71-79:⚠️ Potential issue | 🟠 MajorTest execution is presented as guaranteed behavior
Line 76–79 implies the agent will run tests automatically whenever tests exist. That is not always true across IDE permissions/tooling contexts. Rephrase as conditional (“if execution is available/approved”) and require explicit user verification.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/quick-fixes_cn.md` around lines 71 - 79, Update the sentence "如果你的项目有测试，智能体会在进行更改后自动运行它们，并迭代直到测试通过。" to a conditional phrasing that reflects permission/tooling limits (e.g. start with "如果环境允许并得到授权，智能体可以尝试运行测试...") and add a requirement that the user explicitly verify or approve test execution and results (add wording like "否则请手动或在获得授权后运行并验证测试"). Ensure the revised text clearly signals that automatic test execution is contingent on available execution capabilities and user approval.docs_cn/how-to/quick-fixes_cn.md-90-92 (1)
90-92:⚠️ Potential issue | 🟠 MajorRollback instruction is incomplete for common failure states
git revert HEADonly applies cleanly after a commit and does not handle uncommitted/bad staged changes in the same flow. Add separate rollback paths for: (1) uncommitted changes and (2) already committed changes.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/quick-fixes_cn.md` around lines 90 - 92, Update the rollback section that currently only shows "git revert HEAD" to cover both uncommitted and committed failure states: add a short flow for uncommitted/bad staged changes using commands like "git restore --staged <file>" or "git restore .", and "git reset --hard" or "git stash save --keep-index" as alternate options; keep the existing committed flow but clarify choices between "git revert HEAD" (safe, creates a new commit) and "git reset --hard HEAD~1" (destructive, rewrites history) so users understand which to use and when.docs_cn/404_cn.md-9-9 (1)
9-9:⚠️ Potential issue | 🟠 Major404 recovery link is fragile
Using
./index_cn.mdon a 404 page is brittle across routing/build modes. Use a stable route path for the Chinese home instead of a file-relative Markdown link.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/404_cn.md` at line 9, The 404 page uses a file-relative link './index_cn.md' which is brittle; replace that markdown link with a stable site route for the Chinese home (e.g. change "[返回首页](./index_cn.md)" in 404_cn.md to use an absolute/site path like "[返回首页](/zh-CN/)" or your configured Chinese home route) so the link works consistently across routing/build modes.docs_cn/explanation/why-solutioning-matters_cn.md-75-77 (1)
75-77:⚠️ Potential issue | 🟠 MajorUncited quantitative claim (“10 倍”)
The “快 10 倍” statement is a hard metric without supporting evidence. Either cite a source or downgrade to non-quantified wording.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/explanation/why-solutioning-matters_cn.md` around lines 75 - 77, The caution block labeled :::caution[成本倍增] contains an uncited quantitative claim "快 10 倍"; either add a citation supporting that specific "10 倍" claim or remove the numeric multiplier and replace "快 10 倍" with a non-quantified phrase (e.g., "显著更快" or "更早发现对齐问题") to avoid asserting an unsupported statistic; update the text inside the :::caution block where the string "快 10 倍" appears accordingly.docs_cn/index_cn.md-10-12 (1)
10-12:⚠️ Potential issue | 🟠 MajorRoadmap CTA routes to English page
Line 11 hardcodes
/roadmap/, which bypasses the Chinese docs and breaks localization consistency. Point this CTA to the Chinese roadmap page/route.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/index_cn.md` around lines 10 - 12, Update the CTA link in docs_cn/index_cn.md (the "[查看路线图 →](/roadmap/)" anchor) so it points to the Chinese roadmap route instead of the hardcoded English path; replace "/roadmap/" with the Chinese-docs route (or use the project's i18n/localized URL helper) so the link resolves to the Chinese roadmap page.docs_cn/reference/modules_cn.md-8-8 (1)
8-8:⚠️ Potential issue | 🟠 MajorModule scoping description is misleading for workflows/tasks
Line 8 implies workflows and tasks are module-scoped deliverables. Installer behavior is intentionally asymmetric: agents are module-filtered, while workflows/tasks are installed globally. Please clarify this to avoid incorrect user expectations.
Based on learnings: "workflows and tasks are cross-cutting methodology artifacts that should always be installed globally... Only agents are module-scoped and should be filtered by selectedModules."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/reference/modules_cn.md` at line 8, The current sentence in modules_cn.md incorrectly implies workflows and tasks are module-scoped; update the wording to clarify installer behavior: state that agents are filtered by selectedModules (module-scoped) while workflows and tasks are installed globally (cross-cutting methodology artifacts). Replace or amend the sentence containing "这些附加模块为内置核心和 BMM（敏捷套件）之外的特定领域提供专门的智能体、工作流和任务" to explicitly call out that only 智能体 (agents) are module-scoped and filtered by selectedModules, whereas 工作流和任务 (workflows and tasks) are installed globally and not filtered.docs_cn/how-to/established-projects_cn.md-20-24 (1)
20-24:⚠️ Potential issue | 🟠 MajorGuidance to clear
docs/is dangerously broadLine 20–24 implies users should remove planning artifacts from
docs/, but on established repositoriesdocs/typically contains canonical project documentation. This instruction can cause accidental deletion of still-needed material. Scope this to BMad-generated artifacts only (or a dedicated subfolder).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/established-projects_cn.md` around lines 20 - 24, 将“清理这些文件。归档它们、删除它们……”的指示从笼统地针对 docs/ 改为仅针对 BMad 生成的产物；明确只移除或归档位于 _bmad-output/planning-artifacts/、_bmad-output/implementation-artifacts/ 或者 docs 下的专用 BMad 子目录（例如 docs/_bmad-generated/）的文件，并保留和排除任何项目的规范文档或手动维护的内容；在文中替换原句以包含这些范围限制并增加一句“不要删除手动维护的或规范性文档”以避免误删。docs_cn/reference/agents_cn.md-15-15 (1)
15-15:⚠️ Potential issue | 🟠 MajorInternal link points to the wrong locale document
Line 15 links to
./commands.md, which does not match the Chinese docs naming convention used in this PR. This should point to./commands_cn.mdto keep users in the Chinese doc set.Suggested fix
-- - 斜杠命令是单独生成的。斜杠命令列表及其定义位置请参阅[命令](./commands.md)。 +- - 斜杠命令是单独生成的。斜杠命令列表及其定义位置请参阅[命令](./commands_cn.md)。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/reference/agents_cn.md` at line 15, Update the internal Markdown link that currently points to "./commands.md" so it targets the Chinese locale document "./commands_cn.md"; locate the line containing the sentence "斜杠命令是单独生成的。斜杠命令列表及其定义位置请参阅[命令](./commands.md)。" and replace the link target to "[命令](./commands_cn.md)" to keep the Chinese docs consistent.docs_cn/index_cn.md-1-4 (1)
1-4:⚠️ Potential issue | 🟠 MajorChinese docs entrypoint is not wired into website content collections
This page is added, but per PR notes the website currently renders only
docs/. Without collection/sidebar wiring fordocs_cn, this content remains effectively unpublished to site users.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/index_cn.md` around lines 1 - 4, The new Chinese landing page docs_cn/index_cn.md isn't hooked into the site content collection; update the docs plugin/site config to register a docs_cn content collection and add an entry for index_cn (or a docs_cn sidebar) so the page is published — specifically add a docs plugin instance or route for the docs_cn collection in your site config (the docs plugin config) and add index_cn to the sidebars configuration so the docs_cn index appears in the site sidebar/navigation.docs_cn/explanation/established-projects-faq_cn.md-11-14 (1)
11-14:⚠️ Potential issue | 🟠 MajorAll anchor links are broken — English anchors don't match Chinese headers.
The table of contents uses English anchors (
#do-i-have-to-run-document-project-first,#what-if-i-forget-to-run-document-project, etc.) but the actual headers are in Chinese. GitHub generates anchors from the header text, so these links will fail.Proposed fix — translate anchors to match Chinese headers
## 问题 -- [我必须先运行 document-project 吗？](`#do-i-have-to-run-document-project-first`) -- [如果我忘记运行 document-project 怎么办？](`#what-if-i-forget-to-run-document-project`) -- [我可以在既有项目上使用快速流程吗？](`#can-i-use-quick-flow-for-established-projects`) -- [如果我的现有代码不遵循最佳实践怎么办？](`#what-if-my-existing-code-doesnt-follow-best-practices`) +- [我必须先运行 document-project 吗？](`#我必须先运行-document-project-吗`) +- [如果我忘记运行 document-project 怎么办？](`#如果我忘记运行-document-project-怎么办`) +- [我可以在既有项目上使用快速流程吗？](`#我可以在既有项目上使用快速流程吗`) +- [如果我的现有代码不遵循最佳实践怎么办？](`#如果我的现有代码不遵循最佳实践怎么办`)Based on learnings: "When documenting cross-reference patterns in Markdown, ensure header anchors follow GitHub's anchor generation rules: lowercase, spaces to hyphens, remove emojis/special characters."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/explanation/established-projects-faq_cn.md` around lines 11 - 14, The TOC anchors in docs_cn/explanation/established-projects-faq_cn.md use English slugs that don't match the Chinese headers; update each link (e.g., the anchors currently written as `#do-i-have-to-run-document-project-first`, `#what-if-i-forget-to-run-document-project`, `#can-i-use-quick-flow-for-established-projects`, `#what-if-my-existing-code-doesnt-follow-best-practices`) to the GitHub-generated anchors for the corresponding Chinese headers by converting the exact Chinese header text to lowercase, replacing spaces with hyphens, and removing emojis/special characters so the links resolve correctly.docs_cn/how-to/shard-large-documents_cn.md-63-70 (1)
63-70:⚠️ Potential issue | 🟠 MajorConfusing priority rules for document discovery.
Line 69 states: "如果两者都存在，完整文档优先 - 如果希望使用分片版本，请删除完整文档"
This creates a destructive workflow requirement: users must delete the original document to use shards. What if:
- They want to keep both for reference?
- They're testing shard performance vs. full document?
- Multiple team members have different preferences?
The discovery mechanism is poorly designed if it requires destructive operations. Where's the configuration flag to choose?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/shard-large-documents_cn.md` around lines 63 - 70, The doc's "工作流程发现机制" paragraph currently mandates deleting the full document to prefer shards; update it to describe a non-destructive preference mechanism instead: replace the sentence "如果两者都存在，完整文档优先 - 如果希望使用分片版本，请删除完整文档" with guidance that users can choose shard-first behavior via a configuration flag (e.g., preferShards or SHARD_PREFERENCE env var) or per-workflow setting; mention fallback rules (explicit config > shard index > full document) and note that both can coexist for testing and team workflows, referencing the "工作流程发现机制" section and the document-name vs document-name/index.md discovery order so readers know which symbols/paths are affected.docs_cn/explanation/preventing-agent-conflicts_cn.md-14-44 (1)
14-44:⚠️ Potential issue | 🟠 MajorConflict examples lack concrete code - purely conceptual.
Lines 14-44 describe three conflict types (API style, database design, state management) but show zero actual code examples. For instance:
The "API Style Conflict" section could show:
// Agent A's code fetch('/users/123') // Agent B's code graphql`{ user(id: 123) { ... } }`Without concrete examples, developers can't recognize these conflicts in their own code. This reads like theory, not actionable guidance.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/explanation/preventing-agent-conflicts_cn.md` around lines 14 - 44, Add concrete, minimal code examples for each conflict section so readers can spot mismatches: in the "API Style Conflict" show Agent A's REST call and Agent B's GraphQL query/operation and an ADR-prescribed GraphQL example; in "Database Design Conflict" show Agent A's snake_case column usage vs Agent B's camelCase column usage plus the standardized schema snippet or migration naming convention; in "State Management Conflict" show Agent A's Redux slice/action names vs Agent B's React Context usage and the ADR-prescribed Redux pattern (e.g., slice/action names) so developers can directly compare and follow the recommended implementation.docs_cn/explanation/quick-flow_cn.md-72-73 (1)
72-73:⚠️ Potential issue | 🟠 MajorNo guidance on preserving work when upgrading mid-project.
Line 73 claims "你的技术规范工作会继续推进" when upgrading from Quick Flow to full BMad Method, but provides zero details on:
- How is the tech-spec transformed into PRD format?
- What manual steps are required?
- Is the transformation automatic or manual?
- What data might be lost in conversion?
This reassurance without substance won't comfort users worried about losing work.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/explanation/quick-flow_cn.md` around lines 72 - 73, Clarify and expand the sentence "你的技术规范工作会继续推进" in docs_cn/explanation/quick-flow_cn.md by adding concrete preservation and migration guidance: describe whether the tech-spec → PRD transformation is automatic or manual, list the exact manual steps a user must perform to upgrade (e.g., export, map sections, import or create PRD), indicate which fields/metadata (comments, attachments, version history, custom fields) may not carry over, and recommend mitigation steps (export backups, copy notes, manual reconciliation). Reference the phrase "你的技术规范工作会继续推进" and ensure the new text explains the conversion process, required user actions, and potential data loss so users know how to preserve work when switching from Quick Flow to full BMad Method.docs_cn/how-to/non-interactive-installation_cn.md-149-171 (1)
149-171:⚠️ Potential issue | 🟠 MajorTroubleshooting section lacks concrete examples and diagnostics.
Lines 149-171 describe problems in abstract terms ("Invalid directory", "未找到模块") but provide no actual error messages, no diagnostic commands, and no systematic debugging approach.
For example:
- What does the actual "Invalid directory" error look like in the terminal?
- How do you check current permissions (
ls -la)?- What does a valid vs. invalid
module.yamllook like?This section won't help users who encounter real problems.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/non-interactive-installation_cn.md` around lines 149 - 171, Expand the Troubleshooting section by replacing abstract bullets under "Invalid directory", "未找到模块", and "自定义内容路径无效" with concrete diagnostic steps and examples: include the exact terminal error strings users will see (e.g., the "Invalid directory" error), shell commands to run for diagnosis (like ls -la, pwd, stat, id, and running with --debug), a short checklist to verify absolute vs relative paths, and one minimal valid vs invalid example of module.yaml showing the required code field; reference the existing headings ("Invalid directory", "未找到模块", "module.yaml", and the --debug flag) so you add these example error messages, commands, and the sample module.yaml content directly under those sections.docs_cn/how-to/non-interactive-installation_cn.md-121-126 (1)
121-126:⚠️ Potential issue | 🟠 MajorMissing post-installation validation guidance.
Section "安装结果" describes what should exist after installation but provides zero guidance on how to verify the installation succeeded. No commands to:
- Check that
_bmad/was created correctly- Validate compiled agents are functional
- Confirm output folder permissions
- Test a simple workflow to ensure end-to-end functionality
Users have no way to distinguish between partial failure and complete success.
Add verification steps section
After line 126, add:
+ +## 验证安装 + +确认安装成功： + +```bash +# 检查目录结构 +ls -la _bmad/ + +# 验证智能体已编译 +ls _bmad/bmm/agents/ + +# 测试简单命令 +/bmad-help +```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/non-interactive-installation_cn.md` around lines 121 - 126, 在“安装结果”段落后添加一段“验证安装”说明，指导用户如何通过具体命令核实安装：检查 `_bmad/` 和 `_bmad-output/` 目录是否存在并查看权限（使用 ls -la 或 stat），列出已编译智能体目录如 `_bmad/bmm/agents/` 以确认代理文件存在，运行一个简单的内置命令或帮助命令（例如 `/bmad-help` 或项目等效命令）以确认工具响应，并建议执行一个最小化工作流/代理调用以验证端到端功能和输出写入 `_bmad-output/`。确保将这些验证步骤作为示例命令片段插入到文件中以便用户复制执行。docs_cn/explanation/advanced-elicitation_cn.md-23-31 (1)
23-31:⚠️ Potential issue | 🟠 MajorNo practical invocation examples or integration guidance.
Lines 23-31 describe the workflow conceptually ("LLM suggests 5 methods", "you select one") but provide zero information on:
- What command or UI action triggers this?
- Where in the development workflow does this appear?
- What does the actual interface look like?
- Can you script or automate method selection?
This reads like a feature description written by someone who's never actually used the feature. Users cannot act on this information.
Add practical invocation guidance
After line 31, add a concrete example:
4. 接受或丢弃，重复或继续 + +## 如何使用 + +在工作流生成内容后，系统会提示： + +```text +是否要对此输出运行高级启发？[y/n] +``` + +选择 `y` 后，AI 会展示 5 种推荐方法供选择。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/explanation/advanced-elicitation_cn.md` around lines 23 - 31, 在“工作原理”小节（当前列出 1–4 步）后添加具体的调用与集成示例，说明触发点和交互格式；例如插入一段中文交互示例提示“是否要对此输出运行高级启发？[y/n]”，并说明用户选择 y 后系统会展示 5 种推荐方法供选择、如何通过 UI（或 CLI）选择方法、是否可自动化/脚本化选择（例如提供参数化命令或 API 调用示例）以及该特性通常在开发流程的哪个阶段出现（例如在生成初稿之后、代码/文档审阅期间）。确保在说明中引用本节“工作原理”并给出明确的用户动作（触发、选择、应用、接受/丢弃）和可复制的交互文本/命令示例。docs_cn/how-to/shard-large-documents_cn.md-10-12 (1)
10-12:⚠️ Potential issue | 🟠 MajorWhy translate deprecated content?
This document is explicitly marked as deprecated ("不再推荐使用此方法") yet receives a full Chinese translation. This is a waste of translation effort and actively confuses users:
- Deprecated features shouldn't be promoted through new documentation
- No migration path - the deprecation notice says it "will become unnecessary" but doesn't say what to do instead
- Contradictory signals - translating it implies it's still important enough to maintain
Either:
- Remove this file entirely from the Chinese translation, OR
- Add a clear section explaining the replacement workflow and migration steps
Proposed alternative: Add migration guidance
:::caution[已弃用] -不再推荐使用此方法，随着工作流程的更新以及大多数主要 LLM 和工具支持子进程，这很快将变得不再必要。 +不再推荐使用此方法，随着工作流程的更新以及大多数主要 LLM 和工具支持子进程，这很快将变得不再必要。 + +**推荐替代方案：** 现代工具和 LLM（Claude 3.5+、GPT-4+）直接支持大型文档。如果您的工具/模型组合支持足够的上下文窗口，请直接使用完整文档，无需分片。 :::🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/shard-large-documents_cn.md` around lines 10 - 12, The Chinese page currently fully translates a deprecated doc marked by the caution block ":::caution[已弃用]"; either remove this translated file from the Chinese docs or update it to include a clear migration section explaining the recommended replacement workflow and explicit migration steps (add a new "替代方案 / 迁移指南" section that references the non-deprecated workflow, tools, and links to canonical English docs), and keep the deprecation notice ":::caution[已弃用]" prominent so readers see it immediately.docs_cn/explanation/quick-flow_cn.md-66-73 (1)
66-73:⚠️ Potential issue | 🟠 MajorVague upgrade detection criteria - no concrete signals specified.
Lines 68-72 mention Quick Flow detects "signals" like "multi-component mentions" and "method uncertainty" but:
- What exactly are these signals?
- What phrases or keywords trigger detection?
- Can users see the detection logic or score?
- How sensitive is the detection?
Users have no way to predict when auto-upgrade triggers or understand why it activated. This is a black box.
Add concrete signal examples
Quick Flow 包含内置的范围检测护栏。当你使用直接请求运行 `quick-dev` 时，它会评估多组件提及、系统级语言和方法不确定性等信号。如果检测到工作超出快速流程范围： + +检测信号示例： +- **多组件提及**："修改前端和后端 API" +- **系统级语言**："重新设计数据库架构" +- **不确定性**："可能需要...""不确定是否..."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/explanation/quick-flow_cn.md` around lines 66 - 73, 在“升级到完整 BMad 方法”/“Quick Flow”段落中补充具体触发信号、示例关键词和可见度说明：列出明确触发器样本（例如“跨多个组件”、“系统级指令冲突”、“模糊实现步骤”、“不确定的方法选择”等短语或正则示例），说明是否向用户展示检测分数或日志（例如“敏感度阈值 = 0.7，得分>阈值触发轻度升级，得分>0.9触发重度升级”），并添加一小节说明用户如何查看或覆写检测（例如在 UI 或 CLI 中的“查看检测详情/手动升级”说明）；在该段落内部保留原始术语（Quick Flow、quick-dev、quick-spec、BMad）以便定位。docs_cn/reference/workflow-map_cn.md-1-104 (1)
1-104:⚠️ Potential issue | 🟠 MajorNo indication whether workflow commands accept Chinese input.
This reference page lists workflow commands like
bmad-brainstorming,bmad-bmm-create-prd, etc., but never addresses:
- Can users interact with these workflows in Chinese?
- Do workflow prompts appear in Chinese or English?
- Can users provide Chinese-language input to requirements gathering?
- Are outputs generated in Chinese if requested?
This is critical information for Chinese-speaking users evaluating whether BMad actually supports their language beyond documentation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/reference/workflow-map_cn.md` around lines 1 - 104, Summary: The doc omits whether workflow commands (e.g., bmad-brainstorming, bmad-bmm-create-prd, bmad-bmm-create-ux-design, bmad-bmm-quick-spec) accept Chinese input or produce Chinese prompts/outputs. Fix: add a clear short subsection after the workflow tables stating language support and how to request Chinese (e.g., "Commands accept Chinese input; prompts and outputs follow the agent's language setting or use '/bmad-help' to switch"), specify whether prompts default to English or localize, and provide the exact command or setting users can use to force Chinese outputs; reference the commands above and the /bmad-help helper so readers know where to change language behavior. Ensure the new text is present in the Chinese doc (docs_cn/reference/workflow-map_cn.md) near the command lists and linked to relevant i18n or help docs.docs_cn/how-to/upgrade-to-v6_cn.md-36-42 (1)
36-42:⚠️ Potential issue | 🟠 MajorIDE cleanup instructions incomplete — cover only Claude, but BMAD supports Cursor, VS Code, and Windsurf.
Lines 38-42 provide cleanup paths only for Claude (
.claude/commands/BMad/) while the codebase supports multiple IDEs:
- Cursor:
.cursor/commands/- VS Code:
.vscode/- Windsurf:
.windsurf/workflows/- Others: installer outputs IDE-specific paths
Add cleanup instructions for all supported IDEs. Explain why legacy command cleanup is necessary (e.g., prevents duplicate command name conflicts). Provide a method for users to locate these directories on their system.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/upgrade-to-v6_cn.md` around lines 36 - 42, Update the IDE cleanup section to cover all supported IDEs by adding removal paths for Cursor (.cursor/commands/), VS Code (.vscode/), and Windsurf (.windsurf/workflows/) in addition to the existing Claude path (.claude/commands/BMad/agents and .claude/commands/BMad/tasks); mention that installer outputs IDE-specific paths so users should also check any installer-specified locations for legacy command folders, and add a brief instruction to locate these directories using the system file explorer or system search (hidden files in the project/home directories) before deleting to avoid duplicate command conflicts.docs_cn/reference/workflow-map_cn.md-16-20 (1)
16-20:⚠️ Potential issue | 🟠 MajorEmbedded workflow diagram is in English; Chinese users see English labels in Chinese documentation.
The diagram at
/workflow-map-diagram.htmlcontains hardcoded English content throughout:
- Phase titles ("Analysis", "Planning", "Solutioning", "Implementation")
- All workflow names ("create-story", "dev-story", "code-review", "retrospective", etc.)
- Agent names ("Bob", "Amelia", "John", "Barry")
- Legend and context flow descriptions
No Chinese variant exists. Both English and Chinese docs reference the same English diagram, creating a poor user experience for Chinese speakers. A localized diagram (
workflow-map-diagram_cn.html) is required to match the translation effort.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/reference/workflow-map_cn.md` around lines 16 - 20, The embedded diagram referenced by the iframe src "/workflow-map-diagram.html" in docs_cn/reference/workflow-map_cn.md is English-only; create a localized Chinese version named "workflow-map-diagram_cn.html" containing translated phase titles, workflow names, agent names, legend and context flow, then update the iframe src in docs_cn/reference/workflow-map_cn.md to point to "/workflow-map-diagram_cn.html" (and optionally keep a link to open the English diagram if needed) so the Chinese documentation displays a matching localized diagram.docs_cn/explanation/preventing-agent-conflicts_cn.md-1-137 (1)
1-137:⚠️ Potential issue | 🟠 MajorAdd links to ADR template and examples.
The document extensively discusses ADRs as the solution to preventing conflicts but provides no practical guidance for writing one. Add:
- Link to the ADR template at
src/bmm/workflows/3-solutioning/create-architecture/architecture-decision-template.md- Link to the create-architecture workflow that guides ADR creation
- An example ADR showing a completed decision record
- Brief guidance on the expected sections: Context, Options Considered, Decision, Rationale, Consequences
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/explanation/preventing-agent-conflicts_cn.md` around lines 1 - 137, Add practical ADR guidance to the "防止智能体冲突" doc: insert a link to the ADR template (architecture-decision-template.md) and a link to the create-architecture workflow, include an example ADR (a completed decision record) and a short guidance checklist listing the expected ADR sections: Context, Options Considered, Decision, Rationale, Consequences; update the section that currently discusses ADRs to reference these resources and place the example ADR near the "通过 ADR 明确决策" section for discoverability.docs_cn/how-to/get-answers-about-bmad_cn.md-84-84 (1)
84-84:⚠️ Potential issue | 🟠 Major示例工作流命名与其他文档不一致，易误导
Line 84 使用
quick-dev，但同批文档中常见实现命令是dev-story。请统一命名或在此处明确两者关系，否则用户会直接调用不存在/非预期命令。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/get-answers-about-bmad_cn.md` at line 84, The workflow example uses the command name `quick-dev` which is inconsistent with other docs that use `dev-story`; update the text to either replace `quick-dev` with `dev-story` for consistency or add a brief clarification stating the relationship (eg. "run `dev-story` (previously `quick-dev`)") so readers won't invoke a non-existent/unexpected command; ensure both `quick-spec` and the chosen implement command (`dev-story` or `quick-dev`) are mentioned consistently.docs_cn/reference/testing_cn.md-39-39 (1)
39-39:⚠️ Potential issue | 🟠 MajorQuinn 能力描述前后矛盾，需统一边界
Line 39 说 Quinn 会“执行并立即修复失败”，但 Line 54 又说 Quinn“仅生成测试”。这会直接误导用户对自动修复能力的预期。请明确：到底是“仅生成”，还是“生成+执行+修复（在何种条件下）”。
Also applies to: 54-54
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/reference/testing_cn.md` at line 39, The Quinn capability wording is inconsistent: update the text around the phrases at the current "运行并验证——执行生成的测试并立即修复失败" (line 39) and the later "仅生成测试" (line 54) so they state the same boundary; choose whether Quinn only generates tests or also executes and fixes them, and make that explicit across both places; if you keep "仅生成测试", change line 39 to a consistent "运行并验证" description like "运行并验证——生成测试，但不执行或自动修复，用户需手动运行并修复失败" (or, if you instead support generation+execution+repair, document the exact conditions and opt-in required, including when automatic fixes run and what scope they cover) so both mentions (the snippet on line 39 and the one on line 54) match and include the required opt-in/conditions for automatic repair.docs_cn/tutorials/getting-started_cn.md-98-98 (1)
98-98:⚠️ Potential issue | 🟠 Major安装步骤与“三种路径”叙述冲突
Line 78-85 讲三种路径，但 Line 98 直接要求“选择 BMad Method”。这会让 Quick Flow / Enterprise 用户按错路径。建议明确“本教程示例选择 BMad Method”，并补充其他路径的安装选择说明。
Also applies to: 78-85
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/tutorials/getting-started_cn.md` at line 98, The doc currently conflicts by describing "三种路径" then forcefully instructing to choose "BMad Method"; update the text around the prompt selection to explicitly state that this tutorial's example will use "BMad Method" and then add brief alternate instructions for the other two paths (e.g., "Quick Flow" and "Enterprise") so users on those paths know the correct selection for their setup; locate and change the sentence that reads "当提示选择模块时，选择 **BMad Method**" to a clarifying sentence like "本教程示例选择 **BMad Method**（Quick Flow/Enterprise 用户请选择相应路径：Quick Flow -> X, Enterprise -> Y）" and add the short bullet or inline note describing which option each path should pick.docs_cn/reference/commands_cn.md-70-70 (1)
70-70:⚠️ Potential issue | 🟠 Major“权威列表”与“残留旧命令”互相冲突
Line 70 把命令目录称为“权威列表”，但 Line 151 明确说旧命令可能残留且不会自动删除。两者不能同时成立。建议改成“当前可见列表，可能包含历史残留项”。
Also applies to: 151-151
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/reference/commands_cn.md` at line 70, Change the contradictory wording: replace the phrase "权威列表" on Line 70 with a neutral phrase such as "当前可见列表，可能包含历史残留项" (or similar), and ensure the description that mentions leftover old commands ("旧命令可能残留且不会自动删除") remains unchanged so both statements are consistent; search for the exact strings "权威列表" and "旧命令可能残留且不会自动删除" to locate and update the occurrences.docs_cn/how-to/get-answers-about-bmad_cn.md-10-10 (1)
10-10:⚠️ Potential issue | 🟠 Major“80% 问题可回答”是无依据的硬指标
Line 10 给出可量化能力承诺，但文档未提供测量口径或来源。建议删除百分比或改为非量化表述，避免用户把营销性表述当成SLA。
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/get-answers-about-bmad_cn.md` at line 10, 当前文档在包含“这个智能指南可以回答超过 80% 的问题”这一可量化承诺（出现在包含“/bmad-help” 的那一句）时没有提供来源或测量口径；请删除该百分比或将其改为非量化表述（例如“可以回答大多数常见问题”或“可回答许多常见问题”），保留并突出 `/bmad-help` 调用方式，同时避免使用看起来像 SLA 的断言词汇；更新包含该句子的段落以反映更中性的表述。docs_cn/reference/commands_cn.md-23-23 (1)
23-23:⚠️ Potential issue | 🟠 Major命令生成机制描述不准确（模块作用域）
Line 23 写成“按选定模块为智能体、工作流、任务、工具都生成命令”。已知设计是：只有智能体按模块过滤；工作流与任务是全局安装。当前描述会让用户误判“缺失命令”是否正常。
Based on learnings, “workflows and tasks ... should always be installed globally... Only agents are module-scoped...”.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/reference/commands_cn.md` at line 23, The documentation line describing the behavior of `npx bmad-method install` is inaccurate about module scoping; update the sentence that currently states commands are generated per selected module for agents, workflows, tasks, and tools to reflect the design: clarify that only agents are filtered by module scope while workflows and tasks (and their command files) are always installed globally, and retain that tools/other artifacts follow the agent/module scoping as appropriate—mention `npx bmad-method install`, "agents", "workflows", and "tasks" so readers can see the correct scoping behavior.
🧹 Nitpick comments (4)
docs_cn/how-to/customize-bmad_cn.md (2)
40-127: Add examples of common mistakes and anti-patterns.The documentation only shows correct usage patterns but lacks examples of what NOT to do. Users would benefit from seeing common mistakes such as:
Common pitfalls to document:
- Invalid YAML indentation that breaks parsing
- Referencing a workflow file that doesn't exist
- Creating circular references in menu items
- Using reserved keywords as IDs
- Mixing tabs and spaces in YAML
- Forgetting to quote strings with special characters
- Using relative paths incorrectly
A "❌ Don't do this" vs "✅ Do this" comparison would prevent many user errors.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/customize-bmad_cn.md` around lines 40 - 127, Add a "Common mistakes & anti-patterns" subsection to this customization guide showing "❌ Don't do this" vs "✅ Do this" examples; include concrete examples for invalid YAML indentation, mixing tabs/spaces, unquoted special-character strings, missing workflow file references, incorrect relative paths, circular menu references, and using reserved keywords as IDs, and place it near the existing sections (referencing sections like agent.metadata, persona, memories, menu, critical_actions, prompts) so readers can see each bad example next to the correct form and preventive tips.
32-38: Provide command to list available agents and verify installation.Lines 32-38 show the expected directory structure but don't explain how users can:
- List which agents are actually installed in their project
- Verify the directory structure is correct
- Identify the customize.yaml file for a specific agent
Add a command like:
ls -la _bmad/_config/agents/or better yet, if BMad provides a CLI command to list agents:
npx bmad-method list-agents🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/how-to/customize-bmad_cn.md` around lines 32 - 38, Add concrete commands to show installed agents and verify the directory structure: instruct users to run a filesystem listing like "ls -la _bmad/_config/agents/" to see actual files (e.g., core-bmad-master.customize.yaml, bmm-dev.customize.yaml) and confirm names/permissions, and also include the BMad CLI check "npx bmad-method list-agents" (if available) to list registered agents; note how to identify a specific agent's customize file by matching the agent name to the corresponding *.customize.yaml filename (e.g., core-bmad-master.customize.yaml) and suggest checking file presence and readable permissions to verify installation.README_CN.md (1)
1-4: Missing language switcher or link to English README.Chinese-speaking users who land on this page have no way to navigate to the English version. Consider adding a language toggle link near the top (e.g.,
[English](README.md) | 中文).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README_CN.md` around lines 1 - 4, Add a language switcher link at the top of README_CN.md so Chinese readers can easily jump to the English README; modify the header area (around the existing banner image and badges) to include a simple toggle like "[English](README.md) | 中文" placed before or after the badges, ensuring the link text points to the English README (README.md) and the current file remains labeled as 中文.docs_cn/explanation/established-projects-faq_cn.md (1)
48-48: Acronym "BMM" used but not defined in glossary.Line 48 uses "BMM" but the glossary (lines 54-60) doesn't include it. Add a definition for consistency with other Chinese docs.
Proposed addition to glossary
- **modernization**：现代化。将旧代码或系统更新为更现代的技术和最佳实践的过程。 +- **BMM**：BMad Method 模块。BMad 方法的核心软件开发模块。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs_cn/explanation/established-projects-faq_cn.md` at line 48, Add an entry for the acronym "BMM" to the document's Chinese glossary so it's defined like other acronyms; locate the glossary block and add a concise Chinese expansion and one-sentence explanation for BMM (matching the tone/format of existing entries) so occurrences such as the line containing "BMM 尊重你的选择——它不会强制现代化，但会提供现代化选项。" are covered.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (29)
README_CN.mddocs_cn/404_cn.mddocs_cn/_STYLE_GUIDE.mddocs_cn/explanation/advanced-elicitation_cn.mddocs_cn/explanation/adversarial-review_cn.mddocs_cn/explanation/brainstorming_cn.mddocs_cn/explanation/established-projects-faq_cn.mddocs_cn/explanation/party-mode_cn.mddocs_cn/explanation/preventing-agent-conflicts_cn.mddocs_cn/explanation/project-context_cn.mddocs_cn/explanation/quick-flow_cn.mddocs_cn/explanation/why-solutioning-matters_cn.mddocs_cn/how-to/customize-bmad_cn.mddocs_cn/how-to/established-projects_cn.mddocs_cn/how-to/get-answers-about-bmad_cn.mddocs_cn/how-to/install-bmad_cn.mddocs_cn/how-to/non-interactive-installation_cn.mddocs_cn/how-to/project-context_cn.mddocs_cn/how-to/quick-fixes_cn.mddocs_cn/how-to/shard-large-documents_cn.mddocs_cn/how-to/upgrade-to-v6_cn.mddocs_cn/index_cn.mddocs_cn/reference/agents_cn.mddocs_cn/reference/commands_cn.mddocs_cn/reference/modules_cn.mddocs_cn/reference/testing_cn.mddocs_cn/reference/workflow-map_cn.mddocs_cn/roadmap_cn.mdxdocs_cn/tutorials/getting-started_cn.md
alexeyv
force-pushed
the
docs/add-chinese-translation
branch
from
8be8226 to
f534403
Compare
alexeyv
left a comment
alexeyv
left a comment
There was a problem hiding this comment.
Thanks for the thorough translation work! Everything looks good -- the translations are faithful and complete.
Just one small fix needed: in docs_cn/reference/commands_cn.md, there is a link pointing to ./modules.md that should be ./modules_cn.md for consistency with the rest of the Chinese docs.
2 participants
What
Add Chinese documentation translation including README and complete docs directory.
Why
To make BMad accessible to Chinese-speaking users and expand the community reach.
How
Testing
Current Status:
docs_cn/directory has been added to the repositorywebsite/) has NOT been updated yetdocs/directory (English docs)Why This Happens:
website/src/content/docsis a symlink to the rootdocs/directorydocs, notdocs_cnNext Steps Needed:
website/src/content/docs_cn→docs_cnwebsite/src/content/config.tsto adddocs_cncollectionwebsite/astro.config.mjsto add Chinese sidebar configurationSuggestion:
This PR focuses on adding the Chinese documentation content. A follow-up PR should be created to configure the website to render these documents. Please advise on the preferred approach for internationalization (i18n) - whether to use Starlight's built-in i18n or a custom solution.