Skip to content

docs(ci): add translation-sync guardrails for README (5 langs) and docs site (en/zh/ja) #419

Description

@lizhengfeng101

Description

The project maintains documentation in two places, each with multiple language variants:

  • README — 5 languages: README.md (en), README.zh-CN.md, README.ja-JP.md, README.ko-KR.md, README.ru-RU.md
  • 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/)
  • For check 审查报告:extra_body 实现一致性问题 + update.js 健壮性缺陷 #2, use the PR's changed-file list (e.g. via git diff --name-only against the base ref, or the GitHub API).

Acceptance Criteria

  • 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions