fix: make docs i18n frontmatter translation resilient by hxy91819 · Pull Request #91578 · openclaw/openclaw

hxy91819 · 2026-06-09T03:03:32Z

Summary

keep exact glossary matches deterministic so entries like LINE -> LINE do not call Codex
consume --output-last-message when Codex produced a translation but exits non-zero
fall back to the source frontmatter scalar when a frontmatter translation call fails, instead of failing the whole localized page
add regression coverage for rewriting stale channels/line localized titles across zh-CN, zh-TW, de, and es

Verification

cd scripts/docs-i18n && go test ./...
git diff --check
.agents/skills/autoreview/scripts/autoreview --mode local
real translator smoke: temporary docs root, one channels/line.md, OPENCLAW_DOCS_I18N_MODEL=gpt-5.3-codex-spark, --thinking low --parallel 1 --overwrite; Codex failed one summary frontmatter call with exit 1, the script fell back for that scalar, completed generation, and rewrote stale title: 行 to title: LINE

Notes

This is PR 1 for the actual translation failure. A separate publish-repo PR can still tighten workflow/finalizer behavior so future translation failures cannot be reported as a silent success.

clawsweeper · 2026-06-09T03:05:20Z

Codex review: passed. Reviewed June 8, 2026, 11:42 PM ET / 03:42 UTC.

Summary
The PR updates the docs i18n Go translator to bypass exact glossary matches, recover non-empty Codex last-message output after a non-zero exit, fall back to source frontmatter scalars on translation errors, and add regression tests.

PR surface: Other +201. Total +201 across 4 files.

Reproducibility: yes. Current main source shows the relevant paths: exact glossary scalars still go through Codex, frontmatter translator errors fail the page, and Codex non-zero exits ignore the last-message file; the PR body also describes a real translator smoke run that hit the failure mode.

Review metrics: 1 noteworthy metric.

Docs translation failure handling: 1 failure mode changed from page failure to frontmatter source fallback. Maintainers should notice because incomplete localized frontmatter can now complete the docs-i18n run unless downstream publish checks catch it.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P2] Decide whether the linked publish-finalizer follow-up must land before this script behavior merges.

Risk before merge

[P2] Merging intentionally changes docs-i18n automation from failing a page on frontmatter scalar translator errors to completing with source-text fallback, so maintainers need to accept whether the open publish-finalizer follow-up can remain separate or must land first.

Maintainer options:

Land With Follow-Up Tracked
Merge this script fix now and rely on the open publish-repo finalizer follow-up to catch incomplete translation runs before release.
Require Finalizer First
Pause this PR until the publish-repo finalizer that fails incomplete docs translation runs is merged or maintainers explicitly decide it is not required before this change.

Next step before merge

[P2] No narrow repair is needed; the remaining action is maintainer acceptance of the docs-i18n automation semantics and the ordering of the linked publish-finalizer follow-up.

Security
Cleared: No concrete security or supply-chain issue found; the PR does not change dependencies, workflows, or lockfiles, and the Codex subprocess remains read-only with an isolated CODEX_HOME.

Review details

Best possible solution:

Land the script fix with the publish-finalizer tightening treated as the required companion if maintainers want CI to fail incomplete translation output; otherwise record source fallback as accepted docs-i18n behavior.

Do we have a high-confidence way to reproduce the issue?

Yes. Current main source shows the relevant paths: exact glossary scalars still go through Codex, frontmatter translator errors fail the page, and Codex non-zero exits ignore the last-message file; the PR body also describes a real translator smoke run that hit the failure mode.

Is this the best way to solve the issue?

Yes, with one maintainer decision. The exact glossary bypass and non-empty last-message recovery are the narrow local fixes; the source fallback for frontmatter translator errors is maintainable if paired with the publish-finalizer policy maintainers want.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 84acb74a6a77.

Label changes

Label changes:

add proof: sufficient: Contributor real behavior proof is sufficient. The maintainer PR body includes after-fix real translator smoke evidence with a temporary docs root, the Codex model used, the fallback observed, and stale LINE title rewrite confirmed.

Label justifications:

P2: This is a normal-priority docs automation bug fix with limited blast radius to generated documentation translation runs.
merge-risk: 🚨 automation: The diff changes docs-i18n failure semantics in a way that can affect whether automated translation runs fail or complete with fallback source text.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (live_output): The maintainer PR body includes after-fix real translator smoke evidence with a temporary docs root, the Codex model used, the fallback observed, and stale LINE title rewrite confirmed.
proof: sufficient: Contributor real behavior proof is sufficient. The maintainer PR body includes after-fix real translator smoke evidence with a temporary docs root, the Codex model used, the fallback observed, and stale LINE title rewrite confirmed.

Evidence reviewed

PR surface:

Other +201. Total +201 across 4 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	0	0	0	0
Tests	0	0	0	0
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	4	209	8	+201
Total	4	209	8	+201

What I checked:

PR implementation: glossary and Codex output handling: At PR head, NewCodexTranslator stores exact glossary mappings, translate returns an exact mapping without calling Codex, and runCodexExecPrompt reads the non-empty --output-last-message file even when the Codex process exits non-zero. (scripts/docs-i18n/translator.go:56, efd98bba14fd)
PR implementation: frontmatter fallback: At PR head, translateSnippet logs a frontmatter fallback and returns the source scalar when translator.Translate fails, and successful frontmatter TM entries now use the document path instead of the full segment id as SourcePath. (scripts/docs-i18n/process.go:215, efd98bba14fd)
Current main behavior being changed: Current main sends every non-empty frontmatter scalar through translator.Translate and returns the translator error, has no exact glossary shortcut in translate, and returns immediately on Codex command error before reading the last-message output file. (scripts/docs-i18n/process.go:205, 84acb74a6a77)
PR regression coverage: The PR adds Go coverage for LINE titles across zh-CN, zh-TW, de, and es without prompting Codex, frontmatter translator failure fallback without TM caching, corrected SourcePath, exact glossary bypass, and non-zero Codex exits with usable last-message output. (scripts/docs-i18n/main_test.go:168, efd98bba14fd)
Codex dependency contract checked: Sibling Codex source defines --output-last-message, writes the final message during print_final_output, exits with status 1 after printing when error_seen is set, and explicitly avoids overwriting the last-message file on failed turns, which matches this PR's read-non-empty-output fallback. (../codex/codex-rs/exec/src/cli.rs:72, 08cb633c06a2)
Owner/history signal: Available current-main history is shallow, but git blame on the relevant docs-i18n translator and frontmatter paths points to commit 9faa741 as the current implementation source for these lines. (scripts/docs-i18n/translator.go:55, 9faa74153612)

Likely related people:

Vincent Koc: The shallow current-main blame and file log point the relevant docs-i18n translator, frontmatter, and doc-mode implementation lines to commit 9faa741. (role: introduced current implementation in available main history; confidence: medium; commits: 9faa74153612; files: scripts/docs-i18n/translator.go, scripts/docs-i18n/process.go, scripts/docs-i18n/doc_mode.go)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

hxy91819 · 2026-06-09T03:16:28Z

@clawsweeper automerge

clawsweeper · 2026-06-09T03:16:30Z

🦞✅
ClawSweeper merged this PR after the passing review.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=efd98bba14fd6d83b6ae76a354780a7afcba0cd6)
Merge status: merged by ClawSweeper automerge
Merged at: 2026-06-09T03:43:01Z
Merge commit: 162957565a3f

What merged:

The PR updates the docs i18n Go translator to bypass exact glossary matches, recover non-empty Codex last-me ... r a non-zero exit, fall back to source frontmatter scalars on translation errors, and add regression tests.
PR surface: Other +201. Total +201 across 4 files.
Reproducibility: yes. Current main source shows the relevant paths: exact glossary scalars still go through ... re the last-message file; the PR body also describes a real translator smoke run that hit the failure mode.

Automerge notes:

PR branch already contained follow-up commit before automerge: fix: make docs i18n frontmatter translation resilient

The automerge loop is complete.

Automerge progress:

2026-06-09 03:17:05 UTC review queued 29bdfb17e41f (queued)

2026-06-09 03:24:01 UTC review passed 29bdfb17e41f (structured ClawSweeper verdict: pass (sha=29bdfb17e41f3114b7b2bb913707d0a99f953...)

2026-06-09 03:24:19 UTC repair queued 29bdfb17e41f (autonomous) Run: https://github.com/openclaw/clawsweeper/actions/runs/27181822785

2026-06-09 03:26:05 UTC repair started (running) in 1s Run: https://github.com/openclaw/clawsweeper/actions/runs/27181822785 automerge-openclaw-openclaw-91578

2026-06-09 03:26:28 UTC validation plan (passed) in 23s Run: https://github.com/openclaw/clawsweeper/actions/runs/27181822785 pnpm check:changed; pnpm lint; pnpm check:test-types

2026-06-09 03:26:33 UTC Codex write preflight (passed) in 29s Run: https://github.com/openclaw/clawsweeper/actions/runs/27181822785 danger-full-access

2026-06-09 03:29:47 UTC Codex edit 1 d44619a1c066 (complete) in 3m 42s Run: https://github.com/openclaw/clawsweeper/actions/runs/27181822785 exit 0

2026-06-09 03:34:05 UTC validation and review 1 efd98bba14fd (base moved) in 8m Run: https://github.com/openclaw/clawsweeper/actions/runs/27181822785 rebased

2026-06-09 03:34:10 UTC repair completed efd98bba14fd (branch updated) in 8m 5s Run: https://github.com/openclaw/clawsweeper/actions/runs/27181822785 initial automerge rebase is delegated to Codex repair

2026-06-09 03:34:09 UTC review queued efd98bba14fd (after repair)

2026-06-09 03:34:11 UTC automerge wait efd98bba14fd (waiting) in 8m 6s Run: https://github.com/openclaw/clawsweeper/actions/runs/27181822785 up to 600s

2026-06-09 03:42:47 UTC review passed efd98bba14fd (structured ClawSweeper verdict: pass (sha=efd98bba14fd6d83b6ae76a354780a7afcba0...)

2026-06-09 03:43:04 UTC merged efd98bba14fd (merged by ClawSweeper automerge)

2026-06-09 03:43:05 UTC repair finished efd98bba14fd (pushed) in 17m Run: https://github.com/openclaw/clawsweeper/actions/runs/27181822785 repair_contributor_branch

Summary: - The PR updates the docs i18n Go translator to bypass exact glossary matches, recover non-empty Codex last-me ... r a non-zero exit, fall back to source frontmatter scalars on translation errors, and add regression tests. - PR surface: Other +201. Total +201 across 4 files. - Reproducibility: yes. Current main source shows the relevant paths: exact glossary scalars still go through ... re the last-message file; the PR body also describes a real translator smoke run that hit the failure mode. Automerge notes: - PR branch already contained follow-up commit before automerge: fix: make docs i18n frontmatter translation resilient Validation: - ClawSweeper review passed for head efd98bb. - Required merge gates passed before the squash merge. Prepared head SHA: efd98bb Review: openclaw#91578 (comment) Co-authored-by: Mason Huang <masonxhuang@tencent.com> Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: hxy91819 Co-authored-by: hxy91819 <8814856+hxy91819@users.noreply.github.com>

Summary: - The PR updates the docs i18n Go translator to bypass exact glossary matches, recover non-empty Codex last-me ... r a non-zero exit, fall back to source frontmatter scalars on translation errors, and add regression tests. - PR surface: Other +201. Total +201 across 4 files. - Reproducibility: yes. Current main source shows the relevant paths: exact glossary scalars still go through ... re the last-message file; the PR body also describes a real translator smoke run that hit the failure mode. Automerge notes: - PR branch already contained follow-up commit before automerge: fix: make docs i18n frontmatter translation resilient Validation: - ClawSweeper review passed for head efd98bba14fd6d83b6ae76a354780a7afcba0cd6. - Required merge gates passed before the squash merge. Prepared head SHA: efd98bba14fd6d83b6ae76a354780a7afcba0cd6 Review: openclaw/openclaw#91578 (comment) Co-authored-by: Mason Huang <masonxhuang@tencent.com> Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: hxy91819 Co-authored-by: hxy91819 <8814856+hxy91819@users.noreply.github.com>

openclaw-barnacle Bot added scripts Repository scripts size: S maintainer Maintainer-authored PR labels Jun 9, 2026

hxy91819 mentioned this pull request Jun 9, 2026

ci: fail incomplete docs translation runs openclaw/docs#38

Merged

hxy91819 and others added 2 commits June 9, 2026 03:34

fix: make docs i18n frontmatter translation resilient

019ffcf

fix: make docs i18n frontmatter translation resilient

efd98bb

clawsweeper Bot force-pushed the codex/docs-i18n-frontmatter-fallback branch from 29bdfb1 to efd98bb Compare June 9, 2026 03:34

openclaw-barnacle Bot added size: M and removed size: S labels Jun 9, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 9, 2026

clawsweeper Bot merged commit 1629575 into main Jun 9, 2026
153 of 155 checks passed

clawsweeper Bot deleted the codex/docs-i18n-frontmatter-fallback branch June 9, 2026 03:43

hxy91819 mentioned this pull request Jun 9, 2026

fix(docs): continue partial i18n batches after file errors #91642

Merged

github-actions Bot mentioned this pull request Jun 9, 2026

📡 Upstream Digest — 2026-06-09 07:39 UTC curtismercier/openclaw-mods#1043

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: make docs i18n frontmatter translation resilient#91578

fix: make docs i18n frontmatter translation resilient#91578
clawsweeper[bot] merged 2 commits into
mainfrom
codex/docs-i18n-frontmatter-fallback

hxy91819 commented Jun 9, 2026

Uh oh!

clawsweeper Bot commented Jun 9, 2026 •

edited

Loading

Uh oh!

hxy91819 commented Jun 9, 2026

Uh oh!

clawsweeper Bot commented Jun 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

hxy91819 commented Jun 9, 2026

Summary

Verification

Notes

Uh oh!

clawsweeper Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hxy91819 commented Jun 9, 2026

Uh oh!

clawsweeper Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

clawsweeper Bot commented Jun 9, 2026 •

edited

Loading

clawsweeper Bot commented Jun 9, 2026 •

edited

Loading