docs(i18n-zh-cn): Translate docs to Chinese#884
Open
HAHH9527 wants to merge 4 commits intoFission-AI:mainfrom
Open
docs(i18n-zh-cn): Translate docs to Chinese#884HAHH9527 wants to merge 4 commits intoFission-AI:mainfrom
HAHH9527 wants to merge 4 commits intoFission-AI:mainfrom
Conversation
- README.md: fix paths to assets/, LICENSE, MAINTAINERS.md (add extra ../) - getting-started.md: link to local Chinese README instead of root English version
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughAdds a complete set of Chinese (zh-CN) translations for OpenSpec documentation plus localization artifacts (proposal, design, spec, tasks, and metadata) that define translation rules and track validation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 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)
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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (8)
openspec/changes/archive/2026-03-27-add-zh-cn-translations/design.md (1)
27-36: Add a language tag to the fenced block to satisfy markdownlint.Line 27 opens a code fence without language, which triggers MD040. Use
text(orbashif preferred) for consistency.Suggested patch
-``` +```text docs/ i18n/ zh-cn/ README.md ← 根 README.md 的翻译 getting-started.md workflows.md commands.md ...</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@openspec/changes/archive/2026-03-27-add-zh-cn-translations/design.mdaround
lines 27 - 36, The fenced code block in design.md that lists the docs/i18n/zh-cn
tree opens withand lacks a language tag (MD040); update that fenced block to use a language identifier (e.g., change the opening fence totext ordirectory listing (the block starting with ``` and the lines "docs/ i18n/ zh-cn/ ...") and add the chosen language token immediately after the opening backticks.docs/i18n/zh-cn/migration-guide.md (1)
102-131: 补齐代码块语言标记以消除 MD040 告警。该文档有多处 fenced code block 未声明语言；统一补成
text/bash/yaml可直接消除 markdownlint 告警。Also applies to: 264-275, 321-323, 327-329, 340-348, 352-361, 367-384, 392-397, 401-408, 420-422, 428-430, 554-569
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/i18n/zh-cn/migration-guide.md` around lines 102 - 131, Several fenced code blocks in migration-guide.md lack language labels causing markdownlint MD040; update each triple-backtick block shown in the diff (e.g., the "Upgrading to the new OpenSpec" example) and the other listed ranges to include an appropriate language tag such as text, bash, or yaml; search for all ``` blocks in docs/i18n/zh-cn/migration-guide.md (including the ranges noted in the review) and replace ``` with ```text, ```bash, or ```yaml depending on the content so markdownlint MD040 is resolved.docs/i18n/zh-cn/commands.md (1)
80-82: 为未标注语言的代码块补充 fenced language。该文件多处三反引号代码块未指定语言，触发 MD040。建议为命令示例标
text或bash，以通过 lint 并提高可读性。Also applies to: 136-138, 159-167, 181-183, 198-217, 233-234, 276-277, 326-327, 394-395, 503-504, 559-560
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/i18n/zh-cn/commands.md` around lines 80 - 82, Several fenced code blocks (e.g., the block containing "/opsx:explore [主题]") are missing a fenced language and trigger MD040; update each triple-backtick code block in this document to include an appropriate language specifier (for command examples use bash or text) so the blocks look like ```bash or ```text; ensure you apply this consistently to all command/example blocks referenced in the review so linting passes and readability improves.docs/i18n/zh-cn/customization.md (1)
11-11: 建议为代码块统一补语言标签。这些围栏代码块缺少语言声明，会持续触发 MD040；补上
text/yaml/bash可提升可读性并减少 lint 噪音。Also applies to: 32-32, 60-60, 190-190, 224-224
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/i18n/zh-cn/customization.md` at line 11, 在文档的围栏代码块中缺少语言标签（例如在包含表格行“**全局覆盖**”的示例以及文档内其它示例处），请为每个 fenced code block 添加合适的语言标记（如 text、yaml、bash 等）以消除 MD040 警告并提升可读性；在该文件的所有示例/代码块（包含表格旁示例和文档中其它独立代码块）统一补上语言声明，确保每个 ``` 后面跟上对应的语言标识。openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md (4)
21-23: Clarify link handling to reduce ambiguity.The phrasing "link targets are preserved or adjusted" is somewhat vague. While the next requirement (lines 25-34) clarifies that internal links should point to Chinese translations and external links remain unchanged, this scenario would benefit from being more explicit upfront.
📝 Suggested enhancement for clarity
#### Scenario: Links remain functional - **WHEN** translating a document containing hyperlinks or relative paths -- **THEN** link targets are preserved or adjusted to point to the correct Chinese translation paths +- **THEN** external link targets are preserved unchanged, and internal documentation links are adjusted to point to the corresponding Chinese translation paths🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md` around lines 21 - 23, Update the "Scenario: Links remain functional" description to remove ambiguity by explicitly stating handling for internal and external links: change the WHEN/THEN bullets under "Scenario: Links remain functional" so the WHEN remains "translating a document containing hyperlinks or relative paths" and the THEN clearly specifies "internal links (relative paths and in-repo anchors) are rewritten to point to the corresponding Chinese translation paths" and "external links (absolute URLs) are preserved unchanged"; reference and edit the Scenario title "Scenario: Links remain functional" and the subsequent bullet lines to reflect this explicit wording.
3-8: Consider clarifying the scope of "all documentation files."The requirement states "All English documentation files SHALL have corresponding Chinese translations," but doesn't specify any exclusions. Consider explicitly stating whether this includes auto-generated files, changelogs, or other special-purpose documentation, or if there are any phased rollout plans.
📝 Suggested enhancement for clarity
### Requirement: Chinese translation completeness -All English documentation files SHALL have corresponding Chinese translations under `docs/i18n/zh-cn/`. +All user-facing English documentation files under `docs/` and the root `README.md` SHALL have corresponding Chinese translations under `docs/i18n/zh-cn/`.Or add an explicit scenario for exclusions if any exist.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md` around lines 3 - 8, The requirement "Chinese translation completeness" is ambiguous about which English docs are in scope; update the spec block for "Requirement: Chinese translation completeness" (and/or the "Scenario: All source files have translations") to explicitly list inclusions/exclusions (e.g., include/exclude auto-generated files, changelogs, README.md, tooling files) or add an additional scenario "Scenario: Exclusions and phased rollout" that enumerates excluded file types and any phased rollout rules; reference the existing headings "Requirement: Chinese translation completeness" and "Scenario: All source files have translations" when adding the clarifying sentence or new scenario.
1-59: Consider adding requirements for translation maintenance and updates.The spec comprehensively covers the initial translation effort but doesn't address ongoing maintenance. Consider adding requirements for:
- Translation synchronization: How translations should be updated when English source documents change
- Staleness indicators: Whether outdated translations should be marked or removed
- Review process: Who reviews and approves translation updates
These requirements would help ensure the Chinese translations remain accurate and up-to-date over time.
💡 Example maintenance requirement
### Requirement: Translation maintenance When English source documentation is updated, the corresponding Chinese translation SHALL be reviewed and updated to reflect the changes. #### Scenario: Source document updated - **WHEN** an English documentation file is modified - **THEN** the corresponding Chinese translation file is flagged for review and update - **AND** the translation is updated within a defined timeframe or marked as potentially outdated🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md` around lines 1 - 59, Add a new "Requirement: Translation maintenance" section to the spec that mandates synchronization, staleness indicators, and a review process; specifically, create a Requirement titled "Translation maintenance" with scenarios "Source document updated" (WHEN English source is modified THEN flag corresponding Chinese file for review and update), "Staleness indicator" (define how to mark/expire outdated translations) and "Review process" (who reviews/approves updates and target update timeframe), ensuring the new titles and scenarios follow the existing style and naming (e.g., use "Requirement: Translation maintenance" and scenario headings exactly as referenced) and place it alongside the other requirements in the spec without modifying any existing English source requirement text.
47-52: Specify the exact disclaimer format and wording.The requirement states that each file should include a disclaimer with "the model name in backtick-wrapped format," but doesn't provide an example of the exact format or required wording. This could lead to inconsistent implementations across different translation files.
📝 Suggested enhancement with example
Add an example to the scenario:
#### Scenario: Disclaimer present at file start - **WHEN** opening any Chinese translation file under `docs/i18n/zh-cn/` - **THEN** the file begins with a blockquote containing the AI translation notice and model name in backtick-wrapped format +- **AND** the disclaimer follows the format: `> 此文档由 AI 翻译，使用的模型是 \`model-name\`。`Or add a separate scenario with a concrete example of the expected disclaimer text.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md` around lines 47 - 52, The spec lacks a concrete example of the required disclaimer, causing inconsistency; update the "Requirement: AI translation disclaimer" and the "Scenario: Disclaimer present at file start" to include an explicit example disclaimer string and a sample block showing exact wording and formatting (a blockquote at top of each file under docs/i18n/zh-cn/), e.g. a one-line blockquote stating "Translated by AI model `MODEL_NAME`." and/or add a separate scenario that mandates that exact phrase and the backtick-wrapped model name so implementers of the rule (references: "AI translation disclaimer", "Disclaimer present at file start", and the docs/i18n/zh-cn/ path) have precise, uniform guidance.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/i18n/zh-cn/commands.md`:
- Around line 203-208: The example's dependency for the "tasks" work item is
inconsistent with the PR's dependency graph; update the example block so "tasks"
lists both dependencies (specs and design) instead of only specs—modify the line
showing "○ tasks （被阻塞 - 依赖：specs）" to indicate "依赖：specs, design" so it matches
the diagram and `/opsx:continue` readiness semantics for the items proposal,
specs, design, tasks.
In `@docs/i18n/zh-cn/customization.md`:
- Line 344: The link `[CLI 参考：Schema 命令](cli.md#schema-commands)` uses an
incorrect anchor and causes broken navigation; update the anchor fragment to
match the actual generated heading ID in cli.md (replace `#schema-commands` with
the correct fragment produced for the Chinese heading for "Schema 命令" or the
English heading if that file is in English), i.e., locate the link text `[CLI
参考：Schema 命令]` in customization.md and change the target URL to
`cli.md#<actual-fragment>` so the link points to the real anchor.
- Around line 54-60: Replace the incorrect mixed-interface example "openspec new
change ..." with the actual supported interfaces: use the terminal subcommand
form starting with "openspec schema ..." for CLI examples, or use the
slash-command form starting with "/opsx:new" for slash-command examples; update
both the block at the current snippet (the lines showing "openspec new change
my-feature ...") and the other occurrences referenced (around the other example)
so all examples consistently use either "openspec schema ..." or "/opsx:new"
rather than the invalid "openspec new change" form.
In `@docs/i18n/zh-cn/opsx.md`:
- Around line 29-39: The fenced code blocks in docs/i18n/zh-cn/opsx.md (notably
the ASCII diagram containing "schema.yaml" and "templates/*.md") are missing
language identifiers and trigger markdownlint MD040; update each triple-backtick
block (including the diagram and all other blocks referenced in the review) to
include an appropriate language tag (e.g., text for ASCII diagrams, bash for
shell snippets, yaml for YAML snippets) so markdownlint stops flagging
MD040—scan for the fenced blocks around the examples (including the diagram with
"schema.yaml"/"templates/*.md") and the other blocks called out in the comment
and add the correct language token to each opening ``` fence.
In `@docs/i18n/zh-cn/README.md`:
- Line 51: 保留的注释 "<!-- TODO: Add GIF demo of /opsx:propose → /opsx:archive
workflow -->" 暗示公开文档未完成，请在合并前处理：要么移除该 TODO 注释；要么替换为实际演示区块（嵌入 GIF 占位图/动画
URL、简短说明文本和替代文字，并明确示例流程为 /opsx:propose → /opsx:archive），确保 README 中不再暴露待办标记。
In `@openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md`:
- Line 4: Replace the non-canonical model identifier `mimo-v2-pro-free` with the
canonical `mimo-v2-pro` in the translated change artifact (the checklist line
containing the AI translation declaration string starting with `> **声明**：`).
Ensure every occurrence of `mimo-v2-pro-free` in this PR is updated to
`mimo-v2-pro` so all change artifacts use the same model name for traceability.
---
Nitpick comments:
In `@docs/i18n/zh-cn/commands.md`:
- Around line 80-82: Several fenced code blocks (e.g., the block containing
"/opsx:explore [主题]") are missing a fenced language and trigger MD040; update
each triple-backtick code block in this document to include an appropriate
language specifier (for command examples use bash or text) so the blocks look
like ```bash or ```text; ensure you apply this consistently to all
command/example blocks referenced in the review so linting passes and
readability improves.
In `@docs/i18n/zh-cn/customization.md`:
- Line 11: 在文档的围栏代码块中缺少语言标签（例如在包含表格行“**全局覆盖**”的示例以及文档内其它示例处），请为每个 fenced code
block 添加合适的语言标记（如 text、yaml、bash 等）以消除 MD040
警告并提升可读性；在该文件的所有示例/代码块（包含表格旁示例和文档中其它独立代码块）统一补上语言声明，确保每个 ``` 后面跟上对应的语言标识。
In `@docs/i18n/zh-cn/migration-guide.md`:
- Around line 102-131: Several fenced code blocks in migration-guide.md lack
language labels causing markdownlint MD040; update each triple-backtick block
shown in the diff (e.g., the "Upgrading to the new OpenSpec" example) and the
other listed ranges to include an appropriate language tag such as text, bash,
or yaml; search for all ``` blocks in docs/i18n/zh-cn/migration-guide.md
(including the ranges noted in the review) and replace ``` with ```text,
```bash, or ```yaml depending on the content so markdownlint MD040 is resolved.
In `@openspec/changes/archive/2026-03-27-add-zh-cn-translations/design.md`:
- Around line 27-36: The fenced code block in design.md that lists the
docs/i18n/zh-cn tree opens with ``` and lacks a language tag (MD040); update
that fenced block to use a language identifier (e.g., change the opening fence
to ```text or ```bash) so markdownlint stops flagging it—locate the code fence
containing the directory listing (the block starting with ``` and the lines
"docs/ i18n/ zh-cn/ ...") and add the chosen language token immediately after
the opening backticks.
In
`@openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md`:
- Around line 21-23: Update the "Scenario: Links remain functional" description
to remove ambiguity by explicitly stating handling for internal and external
links: change the WHEN/THEN bullets under "Scenario: Links remain functional" so
the WHEN remains "translating a document containing hyperlinks or relative
paths" and the THEN clearly specifies "internal links (relative paths and
in-repo anchors) are rewritten to point to the corresponding Chinese translation
paths" and "external links (absolute URLs) are preserved unchanged"; reference
and edit the Scenario title "Scenario: Links remain functional" and the
subsequent bullet lines to reflect this explicit wording.
- Around line 3-8: The requirement "Chinese translation completeness" is
ambiguous about which English docs are in scope; update the spec block for
"Requirement: Chinese translation completeness" (and/or the "Scenario: All
source files have translations") to explicitly list inclusions/exclusions (e.g.,
include/exclude auto-generated files, changelogs, README.md, tooling files) or
add an additional scenario "Scenario: Exclusions and phased rollout" that
enumerates excluded file types and any phased rollout rules; reference the
existing headings "Requirement: Chinese translation completeness" and "Scenario:
All source files have translations" when adding the clarifying sentence or new
scenario.
- Around line 1-59: Add a new "Requirement: Translation maintenance" section to
the spec that mandates synchronization, staleness indicators, and a review
process; specifically, create a Requirement titled "Translation maintenance"
with scenarios "Source document updated" (WHEN English source is modified THEN
flag corresponding Chinese file for review and update), "Staleness indicator"
(define how to mark/expire outdated translations) and "Review process" (who
reviews/approves updates and target update timeframe), ensuring the new titles
and scenarios follow the existing style and naming (e.g., use "Requirement:
Translation maintenance" and scenario headings exactly as referenced) and place
it alongside the other requirements in the spec without modifying any existing
English source requirement text.
- Around line 47-52: The spec lacks a concrete example of the required
disclaimer, causing inconsistency; update the "Requirement: AI translation
disclaimer" and the "Scenario: Disclaimer present at file start" to include an
explicit example disclaimer string and a sample block showing exact wording and
formatting (a blockquote at top of each file under docs/i18n/zh-cn/), e.g. a
one-line blockquote stating "Translated by AI model `MODEL_NAME`." and/or add a
separate scenario that mandates that exact phrase and the backtick-wrapped model
name so implementers of the rule (references: "AI translation disclaimer",
"Disclaimer present at file start", and the docs/i18n/zh-cn/ path) have precise,
uniform guidance.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 83c966e7-be50-4970-b009-b91d50c3ad19
📒 Files selected for processing (17)
docs/i18n/zh-cn/README.mddocs/i18n/zh-cn/cli.mddocs/i18n/zh-cn/commands.mddocs/i18n/zh-cn/concepts.mddocs/i18n/zh-cn/customization.mddocs/i18n/zh-cn/getting-started.mddocs/i18n/zh-cn/installation.mddocs/i18n/zh-cn/migration-guide.mddocs/i18n/zh-cn/multi-language.mddocs/i18n/zh-cn/opsx.mddocs/i18n/zh-cn/supported-tools.mddocs/i18n/zh-cn/workflows.mdopenspec/changes/archive/2026-03-27-add-zh-cn-translations/.openspec.yamlopenspec/changes/archive/2026-03-27-add-zh-cn-translations/design.mdopenspec/changes/archive/2026-03-27-add-zh-cn-translations/proposal.mdopenspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.mdopenspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md
openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md
Outdated
Show resolved
Hide resolved
- fix customization.md to cli.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Author
|
@coderabbitai help |
Contributor
ChatThere are 3 ways to chat with CodeRabbit:
CodeRabbit commands
Other keywords and placeholders
Status, support, documentation and community
|
Author
|
@coderabbitai review |
Contributor
✅ Actions performedReview triggered.
|
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
1 participant
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.
Summary by CodeRabbit