Skip to content

docs: resync translated READMEs with English source, add sync check - #63

Merged
ZhuYaoHui1998 merged 2 commits into
Seeed-Projects:mainfrom
Chirag6722:fix/readme-translation-drift
Aug 22, 2026
Merged

docs: resync translated READMEs with English source, add sync check#63
ZhuYaoHui1998 merged 2 commits into
Seeed-Projects:mainfrom
Chirag6722:fix/readme-translation-drift

Conversation

@Chirag6722

Copy link
Copy Markdown

Closes #62

What this changes

The English README is maintained; the translations follow when someone remembers. This fixes the four places where they had stopped agreeing, and adds a check so the next one is caught in review.

Finding Where Evidence it is the translation that is wrong
DM max reach given as 650 mm README_zh.md Commit 065c9f2 corrected 650 → 767 mm in README.md on 2026-06-16; Fr, JP and es followed, zh did not
RS Isaac Sim marked planned README_zh.md, README_JP.md, README_Fr.md Rows link to Seeed-Projects/reBot-Isaacsim — pushed to this week — while calling the work planned. EN and es already say completed
reSpeaker voice row missing README_zh.md 12 roadmap rows against 13 everywhere else; #39 added the row to the other languages
RS roadmap table is in French, no section heading README_JP.md 10 rows of ✅ Terminé / ⏳ Prévu copied from README_Fr.md; the other four files all have ### reBot Arm B601 RS

The Isaac Sim one has a visible cost: #47 is still open asking whether Isaac Sim integration exists. It shipped — but three of five READMEs say otherwise, and two of those contradict themselves within a single table row.

The Japanese RS table is translated from the English table, not from the French one it replaced, so it also picks up the corrections the French copy was missing.

The check

tools/check_readme_sync.py compares each translation against README.md on the things that must not differ:

  • number of roadmap tables, and rows per table
  • the status glyph (✅ / 🚧 / ⏳) on every row
  • the numbers in the specification table

It never compares prose — translators keep their own phrasing, and 1,5 kg is treated as equal to 1.5kg so locale decimal separators do not trip it. .github/workflows/readme-sync.yml runs it on pull requests touching README*.md, along with the checker's own tests. Both actions are SHA-pinned, matching #56 and #58.

Verification

  • Run against the pre-fix tree (via a worktree on main), the checker reports exactly the findings above and exits 1:
    README_zh.md: roadmap table 1 has 12 rows, README.md has 13 — a row was added or removed in one and not the other
    README_zh.md: roadmap table 2 row 9 is marked '⏳', README.md marks it '✅'
    README_zh.md: specification reach is [['650'], ['754']], README.md says [['767'], ['754']]
    README_JP.md: roadmap table 2 row 9 is marked '⏳', README.md marks it '✅'
    README_Fr.md: roadmap table 2 row 9 is marked '⏳', README.md marks it '✅'
    
  • Run against this branch: 4 translations agree with README.md., exit 0.
  • 9 unittest cases pass, covering each real bug as a regression test (stale status, missing row, superseded spec), plus locale decimals, a missing file, and an extra table. One test runs the checker against this repository's actual READMEs.
  • actionlint passes on the new workflow. No new links introduced — the Chinese reSpeaker row points at wiki.seeedstudio.com/cn/control_rebot_arm_using_voice_with_respeaker_flex/, confirmed 200, matching the /cn/ convention the other Chinese rows use.

Limits worth knowing

The checker compares structure and numbers, not meaning. It would not have flagged the French-table-in-README_JP.md as "wrong language" — it caught that file only because the French table also carried a stale Isaac Sim status. Detecting a translated file written in the wrong language is a different problem and I have not tried to solve it here.

Note on merge order

This touches README_JP.md:158, which is the line #61 fixes. Whichever merges first, the other needs a trivial rebase — the hunk #61 edits is inside the French table this PR deletes. Merging #61 first is the simpler order.

🤖 Generated with Claude Code

Chirag6722 and others added 2 commits August 20, 2026 21:55
The weekly link check has been failing on main since 2026-08-17. Two
links, in README_Fr.md and README_JP.md, target
./hardware/reBot_B601_RS/readme.md, but that directory holds README.md
in uppercase — the RS folder uses README.md while the DM folder beside
it uses readme.md. GitHub serves paths case-sensitively, so both 404.

These slipped through review in Seeed-Projects#58 because that verification ran on a
case-insensitive Windows filesystem, where readme.md resolves to
README.md and reports as fine. The CI job runs on ubuntu-latest, which
is why it caught them on its first scheduled run.

Closes Seeed-Projects#60

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four factual disagreements between README.md and its translations, each
one English being updated and the copies not following:

- README_zh.md gave DM max reach as 650 mm. Commit 065c9f2 corrected
  that to 767 mm in English on 2026-06-16 and Fr/JP/es followed; zh did
  not. 117 mm is enough to size a workcell wrong.
- The RS Isaac Sim row was marked planned in zh, JP and Fr while linking
  to Seeed-Projects/reBot-Isaacsim in the same row. The work shipped;
  Seeed-Projects#47 is still open asking about it.
- README_zh.md was missing the reSpeaker voice integration row that Seeed-Projects#39
  added everywhere else, so the Chinese roadmap had 12 rows against 13.
- README_JP.md carried the entire RS roadmap table in French, copied
  from README_Fr.md, and had no "### reBot Arm B601 RS" heading.

Add tools/check_readme_sync.py, which compares the translations against
README.md on roadmap table count, rows per table, per-row status glyph
and specification numbers, ignoring prose so translators keep their
phrasing. Run against the pre-fix tree it reports all four findings.
Covered by nine unittest cases and run in CI on README changes.

Closes Seeed-Projects#62

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Chirag6722
Chirag6722 force-pushed the fix/readme-translation-drift branch from f756509 to a5d9092 Compare August 21, 2026 06:10
@Chirag6722

Copy link
Copy Markdown
Author

Rebased onto the branch behind #61 so this stands green on its own.

Before the rebase, the link check on this PR reported one error: README_Fr.md:159 pointing at hardware/reBot_B601_RS/readme.md instead of README.md. That is the bug #61 fixes and it lives on main — this PR had already removed the second instance by replacing the French table in README_JP.md, so the count went 2 → 1 rather than anything new being introduced.

Both checks now pass on this branch: Check Documentation Links ✅ and Check README Translations ✅ (444 unique links, 0 errors; 9 unit tests).

Merge order no longer matters. #61 is now an ancestor of this branch, so merging this closes both #60 and #62; merging #61 first also works and leaves this a clean fast-forward. #61 is still worth keeping open as the smaller, more reviewable change if you would rather take the one-line fix first.

@ZhuYaoHui1998
ZhuYaoHui1998 merged commit 338a14f into Seeed-Projects:main Aug 22, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Translated READMEs contradict the English source: wrong reach spec, missing rows, stale Isaac Sim status, a French table in README_JP

2 participants