You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Docs site — 3 languages under pages/src/content/docs/{en,zh,ja}/
Today, keeping translations in sync is a manual convention (see CLAUDE.md: "When modifying README.md, always sync the changes to all localized versions"). Nothing enforces it, so it is easy to update one language and silently leave the others stale — causing the localized docs to drift out of sync over time.
We should add lightweight CI guardrails that detect drift and warn contributors, without trying to verify translation quality.
Proposal
1. README heading-structure check. Verify that all 5 README files share the same ## section structure (same number and order of top-level sections). The English and Chinese READMEs currently align 1:1, e.g.:
## What is Open Code Review? <-> ## Open Code Review 是什么?
## Benchmark <-> ## 基准测试
## Why Open Code Review? <-> ## 为什么选择 Open Code Review?
## How to Use <-> ## 如何使用
...
If one README gains/loses/reorders a ## section but the others don't, it almost always means a translation sync was missed. The check compares heading counts and ordering (not text, since headings are translated) and fails CI with a clear message pointing at the offending file.
2. Docs-site staleness reminder. In a pull request, if a file under pages/src/content/docs/en/** is modified but its zh/** and/or ja/** counterpart is not touched in the same PR, emit a warning (a non-blocking PR comment, or a soft CI annotation). This flags "en changed, translations may be stale" so reviewers/contributors remember to follow up.
Recommendation: make check 1 blocking (structural mismatch is a real error) and check 2 non-blocking (a warning/annotation), since a legitimate PR may intentionally update only the English source first.
Scope
New script(s): scripts/github-actions/ (follow the existing pattern — a Node script + *.test.js, e.g. alongside post-review-comments.js)
CI wiring: .github/workflows/ci.yml (runs on push / pull_request)
Inputs to consider:
README set: the 5 README*.md files at repo root
Docs pairs: pages/src/content/docs/en/** <-> zh/** / ja/** (mirror the same relative path, including integrations/)
A CI check fails when the 5 README files have mismatched ## section counts/ordering, with a message naming the divergent file(s)
A CI step warns (non-blocking) when docs/en/** files change in a PR without the matching zh/ja files being updated, listing the specific paths
The heading check tolerates translated heading text (compares structure, not literal strings)
Unit tests cover: matching structure (pass), a dropped/added/reordered section (fail), and the docs en-only-change case (warn)
Tests pass (make test)
Code check passes (make check)
Context
Discovered while reviewing the substantial content overlap between the README and the docs site. The multi-language sync burden (5 READMEs + 3-language docs) currently relies entirely on human discipline; these guardrails make drift visible in CI instead of surfacing later as inconsistent docs. Kept intentionally simple — structure/presence checks only, no NLP or translation validation — to stay approachable as a first contribution.
Description
The project maintains documentation in two places, each with multiple language variants:
README.md(en),README.zh-CN.md,README.ja-JP.md,README.ko-KR.md,README.ru-RU.mdpages/src/content/docs/{en,zh,ja}/Today, keeping translations in sync is a manual convention (see
CLAUDE.md: "When modifying README.md, always sync the changes to all localized versions"). Nothing enforces it, so it is easy to update one language and silently leave the others stale — causing the localized docs to drift out of sync over time.We should add lightweight CI guardrails that detect drift and warn contributors, without trying to verify translation quality.
Proposal
1. README heading-structure check. Verify that all 5 README files share the same
##section structure (same number and order of top-level sections). The English and Chinese READMEs currently align 1:1, e.g.:If one README gains/loses/reorders a
##section but the others don't, it almost always means a translation sync was missed. The check compares heading counts and ordering (not text, since headings are translated) and fails CI with a clear message pointing at the offending file.2. Docs-site staleness reminder. In a pull request, if a file under
pages/src/content/docs/en/**is modified but itszh/**and/orja/**counterpart is not touched in the same PR, emit a warning (a non-blocking PR comment, or a soft CI annotation). This flags "en changed, translations may be stale" so reviewers/contributors remember to follow up.Recommendation: make check 1 blocking (structural mismatch is a real error) and check 2 non-blocking (a warning/annotation), since a legitimate PR may intentionally update only the English source first.
Scope
scripts/github-actions/(follow the existing pattern — a Node script +*.test.js, e.g. alongsidepost-review-comments.js).github/workflows/ci.yml(runs onpush/pull_request)README*.mdfiles at repo rootpages/src/content/docs/en/**<->zh/**/ja/**(mirror the same relative path, includingintegrations/)git diff --name-onlyagainst the base ref, or the GitHub API).Acceptance Criteria
##section counts/ordering, with a message naming the divergent file(s)docs/en/**files change in a PR without the matchingzh/jafiles being updated, listing the specific pathsmake test)make check)Context
Discovered while reviewing the substantial content overlap between the README and the docs site. The multi-language sync burden (5 READMEs + 3-language docs) currently relies entirely on human discipline; these guardrails make drift visible in CI instead of surfacing later as inconsistent docs. Kept intentionally simple — structure/presence checks only, no NLP or translation validation — to stay approachable as a first contribution.