docs: relocalize stale locale links by hxy91819 · Pull Request #61796 · openclaw/openclaw

hxy91819 · 2026-04-06T09:41:20Z

Summary

switch docs i18n to a single locale-link postprocess stage instead of localizing links both during per-page translation and again afterward
scope postprocessing to only the localized files successfully emitted in the current run
add regression tests covering stale index-page links and scoped postprocess behavior
add a pipeline-level regression test that runs the docs-i18n main flow with a fake translator and asserts the final localized page links are corrected
touch the gateway runbook copy so zh-CN and ja-JP regenerate and pick up the fixed localized links

Verification trigger

the tiny wording-only change in docs/gateway/index.md is intentional
it forces the /gateway locale pages back through the publish/translation pipeline so we can verify the stale locale-link fix actually propagates in openclaw/docs
this keeps the validation tied to the real generated locale flow instead of relying only on local fixtures

Test plan

go test ./... in scripts/docs-i18n

Root cause

the existing pipeline previously localized links while translating each individual page
files are processed in path-sorted order (scripts/docs-i18n/order.go), so index pages like gateway/index.md can be translated before locale child pages such as gateway/troubleshooting.md exist
link localization only prefixes a route when the localized target page already exists in localizedRoutes (scripts/docs-i18n/localized_links.go)
doc-mode skip logic only compares the English source hash (scripts/docs-i18n/doc_mode.go), so once a page is written with stale English links it will usually be skipped on later runs unless the English source changes

Design

Current design before this PR:

flowchart TD
    A[Collect changed English docs] --> B[Sort files by relative path]
    B --> C[Translate one page]
    C --> D[Try to localize links immediately]
    D --> E{Does localized target page already exist?}
    E -- yes --> F[Write locale-prefixed link]
    E -- no --> G[Keep English root-relative link]
    F --> H[Write localized page]
    G --> H
    H --> I[Future runs compare only source_hash]
    I --> J[Page usually skipped unless English source changes]

Redesigned flow in this PR:

flowchart TD
    A[Collect changed English docs] --> B[Sort files by relative path]
    B --> C[Translate one page]
    C --> D[Write localized page without link rewriting]
    D --> E{Page write succeeded?}
    E -- yes --> F[Add output path to successful file set]
    E -- no --> G[Return run error]
    F --> H[Repeat for remaining pages]
    G --> I[Stop translation loop]
    H --> J[Save translation memory]
    I --> J
    J --> K[Build route index from full locale tree]
    K --> L[Postprocess only files in successful file set]
    L --> M[Rewrite links using final localized route set]
    M --> N[Exit success or return original run error]

    classDef highlight fill:#ffe8a3,stroke:#b7791f,stroke-width:2px,color:#111;
    classDef success fill:#d9f99d,stroke:#4d7c0f,stroke-width:2px,color:#111;
    class F,L,M highlight;
    class E success;

What changed in the design

removed duplicate link-localization logic from the translation path
made localization order-independent by rewriting links only after the target locale tree exists
kept localized_links.go as the single place that decides whether a route should gain a locale prefix
scoped postprocessing to the files successfully emitted in the current run, so failed runs do not rewrite unrelated localized docs
preserved partial-run correctness by still postprocessing files that were successfully written before a later failure

Context

fixes stale localized links like /zh-CN/gateway and /ja-JP/gateway pointing some body links at English routes even when localized target pages exist
also explains why pages like /zh-CN/providers could already look correct: those links were localized successfully because their target locale pages already existed when that page was translated

greptile-apps · 2026-04-06T09:43:21Z

Greptile Summary

This PR fixes a longstanding ordering bug in the docs i18n pipeline where index pages translated before their child locale pages existed would retain stale English links instead of locale-prefixed ones. The fix decouples link localization from the per-page translation step and instead runs a single postprocess pass (postprocessLocalizedDocs) over the full locale tree after all translations are written — ensuring localizeBodyLinks always sees the complete route index.

Key changes:

Removed the routes *routeIndex parameter from processFileDoc, processFile, and their callers — link rewriting no longer happens during translation
Added relocalize.go with postprocessLocalizedDocs, which loads the route index after the full locale tree exists and rewrites any remaining English-root links that now have localized targets
Moved loadRouteIndex from main() startup to inside postprocessLocalizedDocs, so it always executes against the final translated file set
Changed error handling in main() from early-exit fatal calls to a deferred runErr variable so that tm.Save() and the postprocess step always run even when translation partially fails
Added a regression test that creates a stale zh-CN gateway/index.md with an English link, creates the localized troubleshooting.md, runs postprocessLocalizedDocs, and asserts both front matter integrity and link rewriting — directly addressing the concerns raised in the previous review round

Confidence Score: 5/5

Safe to merge; the redesign is correct and all prior review concerns have been addressed in this revision.

The previous P1 concern about missing newline before the closing front-matter delimiter is resolved: the reconstruction in relocalize.go uses '"---
" + frontMatter + "
---

"', which correctly separates the YAML block from the body. The follow-up concern about the test not validating front matter structure is also addressed — the test now asserts the exact front-matter string. The core logic is sound: deferring loadRouteIndex to run after translation completes makes link-rewriting fully order-independent. No P0 or P1 issues remain; only a trivial stdlib-vs-helper style nit on stringsJoin.

No files require special attention.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: scripts/docs-i18n/relocalize_test.go
Line: 50-58

Comment:
**Redundant `stringsJoin` helper**

This helper is functionally identical to `strings.Join(lines, "\n")` from the standard library. Replacing it keeps the test helpers minimal and avoids dead code.

```suggestion
func stringsJoin(lines ...string) string {
	return strings.Join(lines, "\n")
}
```

How can I resolve this? If you propose a fix, please make it concise.

_{Greploops — Automatically fix all review issues by running /greploops in Claude Code. It iterates: fix, push, re-review, repeat until 5/5 confidence.
Use the Greptile plugin for Claude Code to query reviews, search comments, and manage custom context directly from your terminal.}

_{Reviews (2): Last reviewed commit: "docs: relocalize partial docs runs" | Re-trigger Greptile}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dfb90dde2c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b71837c365

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

hxy91819 · 2026-04-06T10:22:32Z

@greptile-apps review
@codex review

chatgpt-codex-connector · 2026-04-06T10:25:56Z

Codex Review: Didn't find any major issues. More of your lovely PRs please.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 56b80002cd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

hxy91819 · 2026-04-06T10:33:34Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e31e1dc59b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

hxy91819 · 2026-04-06T11:36:55Z

@codex review

chatgpt-codex-connector · 2026-04-06T11:42:22Z

Codex Review: Didn't find any major issues. Delightful!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

hxy91819 · 2026-04-06T14:15:40Z

@codex review

chatgpt-codex-connector · 2026-04-06T14:21:22Z

Codex Review: Didn't find any major issues. What shall we delve into next?

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: faa6890309

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-06T14:40:17Z

 	output := updatedFront + translatedBody
-	return false, os.WriteFile(outputPath, []byte(output), 0o644)
+	return false, outputPath, os.WriteFile(outputPath, []byte(output), 0o644)


Avoid finalizing doc output before relocalize succeeds

This writes the translated file (including a fresh x-i18n.source_hash) before link relocalization runs in runDocsI18N, so if the later postprocessLocalizedDocs step errors (for example on route-index/file I/O), the doc is left with stale English-root links but will be treated as up-to-date on retry with --overwrite=false via shouldSkipDoc. That makes a failed run sticky: reruns can skip the broken file indefinitely unless the source changes or overwrite is forced.

Useful? React with 👍 / 👎.

* docs: relocalize stale locale links * docs: unify locale link postprocessing * docs: preserve relocalized frontmatter * docs: relocalize partial docs runs * docs: scope locale link postprocessing * docs: continue scoped relocalization * docs: drain parallel i18n results * docs: add i18n pipeline link regression tests * docs: clarify i18n pipeline regression test intent * docs: update provider references in i18n tests to use example-provider * fix: note docs i18n link relocalization * docs: rephrase gateway local ws sentence

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime scripts Repository scripts size: S maintainer Maintainer-authored PR labels Apr 6, 2026

greptile-apps Bot reviewed Apr 6, 2026

View reviewed changes

Comment thread scripts/docs-i18n/relocalize.go Outdated

Comment thread scripts/docs-i18n/relocalize_test.go

chatgpt-codex-connector Bot reviewed Apr 6, 2026

View reviewed changes

Comment thread scripts/docs-i18n/relocalize.go Outdated

chatgpt-codex-connector Bot reviewed Apr 6, 2026

View reviewed changes

Comment thread scripts/docs-i18n/main.go Outdated

openclaw-barnacle Bot added size: M and removed size: S labels Apr 6, 2026

chatgpt-codex-connector Bot reviewed Apr 6, 2026

View reviewed changes

Comment thread scripts/docs-i18n/relocalize.go Outdated

chatgpt-codex-connector Bot reviewed Apr 6, 2026

View reviewed changes

Comment thread scripts/docs-i18n/main.go Outdated

hxy91819 self-assigned this Apr 6, 2026

openclaw-barnacle Bot added size: L and removed size: M labels Apr 6, 2026

hxy91819 force-pushed the fix-docs-localized-links branch from dea1f52 to 3c90456 Compare April 6, 2026 11:36

hxy91819 force-pushed the fix-docs-localized-links branch 4 times, most recently from 3082ae7 to 11e5d14 Compare April 6, 2026 14:14

hxy91819 force-pushed the fix-docs-localized-links branch 2 times, most recently from 236c5b5 to 5b69b22 Compare April 6, 2026 14:28

hxy91819 added 12 commits April 6, 2026 22:32

docs: relocalize stale locale links

7b9568c

docs: unify locale link postprocessing

3187c28

docs: preserve relocalized frontmatter

cec87f7

docs: relocalize partial docs runs

a998e76

docs: scope locale link postprocessing

292a588

docs: continue scoped relocalization

7820cf1

docs: drain parallel i18n results

23eb510

docs: add i18n pipeline link regression tests

3d7593d

docs: clarify i18n pipeline regression test intent

0142115

docs: update provider references in i18n tests to use example-provider

e337a02

fix: note docs i18n link relocalization

6cfa644

docs: rephrase gateway local ws sentence

faa6890

hxy91819 force-pushed the fix-docs-localized-links branch from 5b69b22 to faa6890 Compare April 6, 2026 14:34

hxy91819 merged commit 9b0ea7c into main Apr 6, 2026
9 checks passed

hxy91819 deleted the fix-docs-localized-links branch April 6, 2026 14:37

chatgpt-codex-connector Bot reviewed Apr 6, 2026

View reviewed changes

github-actions Bot mentioned this pull request Apr 6, 2026

📡 Upstream Digest — 2026-04-06 14:40 UTC curtismercier/openclaw-mods#488

Open

Uh oh!

Uh oh!

Conversation

hxy91819 commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification trigger

Test plan

Root cause

Design

What changed in the design

Context

Uh oh!

greptile-apps Bot commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

hxy91819 commented Apr 6, 2026

Uh oh!

chatgpt-codex-connector Bot commented Apr 6, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

hxy91819 commented Apr 6, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

hxy91819 commented Apr 6, 2026

Uh oh!

chatgpt-codex-connector Bot commented Apr 6, 2026

Uh oh!

hxy91819 commented Apr 6, 2026

Uh oh!

chatgpt-codex-connector Bot commented Apr 6, 2026

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

hxy91819 commented Apr 6, 2026 •

edited

Loading

greptile-apps Bot commented Apr 6, 2026 •

edited

Loading