RFC 0024: Localization Runtime and Product Coverage

[giodl73-repo]

Why this RFC is needed

OpenClaw already has localized Control UI, native-app, documentation, and onboarding paths, but users cross into English or locale-dependent behavior outside those bounded surfaces. The gaps span locale precedence, Gateway compatibility, runtime safety copy, command and skill metadata, channel recipient ownership, and trustworthy release evidence.

The issue-to-contract mapping is in the RFC issue catalog.

Decision requested

Approve these product contracts:

1. One immutable LocalizationContext resolves locale with explicit user and recipient choices ahead of inference and a deterministic English fallback.
2. Product-owned runtime copy uses stable message keys, typed scalar parameters, reviewed English recovery templates, and edge-owned rendering. Shared JavaScript/TypeScript catalogs use intl-messageformat; OpenClaw retains context, validation, fallback, and safety.
3. Gateway errors preserve codes and the legacy English message; reviewed errors may add bounded details.localization metadata after protocol-owner approval and compatibility proof.
4. Commands, skills, and plugins retain stable identities while owners may adopt additive localized presentation metadata.
5. Surface owners publish generic coverage declarations. Product release policy—not the localization kernel—owns the portfolio, maturity target, reviewer roster, and completion claim.
6. High-risk families fail closed to reviewed English and require family/locale-scoped review evidence tied to exact catalogs and policy.

Stable codes, commands, flags, config keys, IDs, paths, provider/model names, and structured output remain compatible. Logs, developer diagnostics, arbitrary exception strings, and model-generated response language remain outside v1.

Acceptance status: Patrick confirmed in Discord that the clarified design and rollout model all makes sense with a thumbs-up reaction. RFC 0024 is accepted and implementation is tracked in openclaw/openclaw#113105; scoped owner approvals remain required where the RFC names them.

Delivery model

RFC acceptance approves contracts; it does not change runtime behavior. Foundation slices then land a small removable kernel and bounded owner consumers. Product completion remains a later, independently evidenced language-by-surface release claim.

The five existing OpenClaw drafts are bounded implementation evidence. F02-F05 now branch independently from F01, so no owner follow-up carries another follow-up slice:

• #111541: locale/context kernel and existing onboarding consumer.
• #111542: updater-owned human update --dry-run output with JSON invariance.
• #111543: contributor ownership and validation guidance.
• #111544: bounded TUI status labels and relative ages.
• #111545: one reviewed APPROVAL_NOT_FOUND descriptor and Control UI edge.

Landing F01 and then the four independent owner slices does not make every language-by-surface cell complete. Owner declarations and aggregate reporting remain later E43/E44 slices.

Draft OpenClaw PR #112784 implements G45/G46: a routine English wizard source change trips credential-free CI, then a trusted exact-source workflow generates and validates locale candidates and opens a generated PR. Later product-string slices must bring both their scoped gate and owner-owned async refresh, or prove an existing workflow conforms.

For review, #112784 contains F01, the exact five-file F03 ownership delta, and the 17-file exemplar; unrelated updater, TUI, Gateway, and approval runtime ancestry is excluded. #112801 adds only the seven-file G47 delta on top.

Draft OpenClaw PR #112801 implements G47: owner adapters enumerate real product-surface registrations or declared product-facing source roots, and CI requires new scopes to be adopted, mapped to a conforming owner pipeline, or explicitly dispositioned with owner evidence. Existing debt is baselined. This is not a repository-wide string-literal scanner or a runtime registry.

The audited projected registry currently has 47 entries:

• F01-F05: current foundation evidence;
• O06-O15: operator-owned terminal and setup surfaces;
• R16-R24: runtime safety and recipient-locale boundaries;
• M25-M36: metadata and channel projections;
• P37-P42: browser, native, and documentation ownership;
• E43-E44: declarations, review evidence, and release promotion;
• G45-G47: scoped authoring, trusted refresh, and new-surface adoption gates.

These are current source-audit slices, not a requirement for 47 PRs or an acceptance gate. Entries may split, combine, or disappear as real source and owner boundaries are confirmed. This uses the useful Doctor registry lesson while keeping Doctor's tracked inventory distinct from localization.

The September 1, 2026 delivery forecast assigns all 47 entries exactly once across 16 dependency-safe packages. The packages average roughly three completions per full week, reuse shared per-repository gates and translation workflows, and count only landed, source-deleted, or conforming owner-pipeline evidence as done.

See the implementation plan and the projected owner-slice registry for ownership, dependencies, gates, and proof bars.

Safety and compatibility

• Gateway projection preserves the reviewed English compatibility message and stable code.
• Invalid descriptor parameters use the owning surface's English compatibility path and never fail the underlying operation.
• Safety review revisions cover descriptor recovery templates, invalidating stale attestations when emergency English changes.
• Metadata validation uses portable v1 limits; adapters may impose stricter platform limits.
• The current portfolio threshold remains product release policy, not an RFC-acceptance or kernel-landing condition.

Validation

• git diff --check
• relative Markdown links validated across RFC 0024 and all sidecars
• 47 projected slice IDs checked for uniqueness
• contract consistency audited across the RFC and sidecars
• exact accepted RFC head: 267e575a67e74c6181438a74ae6199e7e3313168

RFC 0024 is accepted; implementation proceeds through the linked owner-gated slices and tracker.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 20, 2026, 3:44 PM ET / 19:44 UTC.

Summary
This PR adds RFC 0024 and five supporting specifications for product-wide locale resolution, localized runtime messages and metadata, Gateway compatibility, coverage governance, and a staged delivery plan.

Reproducibility: not applicable. This PR is a design RFC, not a report of one currently failing behavior. Its cited localization gaps require separate validation in the linked implementation work.

Review metrics: 2 noteworthy metrics.

• RFC surface: 6 files added; 2,666 lines added. The PR establishes a broad product contract and supporting specifications rather than a narrow documentation correction.
• Delivery structure: 5 foundation slices and 5 completion slices. The staged plan makes acceptance dependent on a product-level decision, not only document accuracy.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
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:

• Obtain explicit product-owner decisions for the five proposed contracts and named ownership gates.

Risk before merge

• [P1] Adopting an immutable locale-precedence model and additive Gateway localization metadata may create lasting compatibility commitments for existing clients, settings, and protocol consumers.
• [P1] The RFC leaves owner decisions unresolved for recipient-locale authority, bounded error inventories, safety-copy attestation, language ownership, and Persian/Thai documentation disposition.

Maintainer options:

1. Approve only with explicit compatibility ownership (recommended)
   Confirm the locale-precedence, legacy Gateway-message, and metadata compatibility guarantees before accepting the RFC as the baseline for implementation work.
2. Split the design decision
   Land or revise only the non-protocol documentation after separating Gateway and recipient-locale policy into owner-approved follow-up RFC work.
3. Pause pending product direction
   Leave the RFC draft open until a product owner sponsors the requested cross-surface contracts and attestation responsibilities.

Next step before merge

• [P1] A product owner must choose the permanent compatibility and ownership model; this is not a narrow automated repair.

Maintainer decision needed

• Question: Should OpenClaw adopt the RFC's shared localization contracts—especially locale precedence and additive Gateway metadata—as the product direction for the linked implementation stack?
• Rationale: The PR defines new cross-product and protocol-facing commitments; source review cannot determine the intended permanent compatibility contract or assign the requested safety and language-review ownership.
• Likely owner: giodl73-repo — They are the only evidence-backed routing contact for the RFC's detailed contract and implementation rationale; final acceptance still requires an OpenClaw product owner.
• Options:
  • Approve a bounded v1 contract (recommended): Adopt the stated compatibility-preserving contracts while requiring each implementation slice to remain within its explicitly owned surface and review gates.
  • Narrow before adoption: Retain the RFC as a design basis but remove or defer Gateway, channel-safety, metadata, or coverage commitments until their owners agree on a smaller first milestone.
  • Decline the unified contract: Keep localization improvements surface-specific rather than committing to the proposed shared runtime and governance model.

Security
Cleared: The proposed diff is documentation-only and no concrete security or supply-chain change is present.

Review details

Best possible solution:

Have product and protocol owners approve, narrow, or reject the five contracts before landing the RFC, then evaluate the linked implementation slices against the accepted compatibility boundary.

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

Not applicable: this PR is a design RFC, not a report of one currently failing behavior. Its cited localization gaps require separate validation in the linked implementation work.

Is this the best way to solve the issue?

Unclear: a shared contract may prevent incompatible per-surface localization work, but the proposed precedence, Gateway, and safety-copy boundaries need explicit product-owner approval before this becomes the best solution.

AGENTS.md: unclear because the file could not be read completely.

Codex review notes: model internal, reasoning high; reviewed against 2d213ae23462.

Label changes

Label justifications:

• P3: This is a forward-looking RFC that needs deliberate product-direction review rather than urgent regression handling.
• merge-risk: 🚨 compatibility: The proposed locale-precedence and Gateway metadata contracts could constrain existing client and configuration compatibility after adoption.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. The RFC offers an unusually comprehensive way to keep runtime, metadata, UI, channel, and release-localization work compatible while preserving surface ownership.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: All reported changed paths are RFC and specification documents, so external runtime proof is not required for this documentation-only PR.

Evidence reviewed

What I checked:

• RFC decision scope: The proposal explicitly asks for approval of locale precedence, runtime message descriptors, additive Gateway localization metadata, localized capability metadata, and a product coverage/release-evidence contract. (rfcs/0024-localization-runtime-and-coverage.md:24, 54b4e5dceaea)
• Implementation remains proposed: The implementation plan identifies the five foundation slices as open for review, so the RFC's central contracts are not shown as accepted or implemented on the RFC repository default branch. (rfcs/0024/implementation-plan.md:9, 54b4e5dceaea)
• Active linked implementation context: The discussion links an upstream foundation stack, including feat(localization): add locale context and message rendering openclaw#111541 through feat(localization): add Gateway approval error descriptor openclaw#111545, and describes them as open for review; this supports keeping the design decision and implementation work separate until owners decide the contract. (54b4e5dceaea)
• Recent proposal refinement: The current head's latest commit is docs(localization): strengthen ownership and conformance, following prior RFC refinements; the branch is actively evolving rather than an obsolete proposal. (rfcs/0024-localization-runtime-and-coverage.md:1, 54b4e5dceaea)

Likely related people:

• giodl73-repo: Authored the RFC branch's documented localization contracts and the linked implementation-stack updates, making them the best available source for design rationale and refinement context. (role: RFC domain author; confidence: medium; commits: 238d7bc51abd, df1a29b514ea, 54b4e5dceaea; files: rfcs/0024-localization-runtime-and-coverage.md, rfcs/0024/implementation-plan.md, rfcs/0024/localization-runtime-v1-spec.md)

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.

Review history (12 earlier review cycles; latest 8 shown)

• reviewed 2026-07-17T23:59:44.549Z sha a67ce60 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-19T19:34:45.790Z sha 238d7bc :: needs real behavior proof before merge. :: none
• reviewed 2026-07-19T21:09:35.390Z sha 30e077e :: needs real behavior proof before merge. :: none
• reviewed 2026-07-19T22:04:27.265Z sha 30e077e :: needs real behavior proof before merge. :: none
• reviewed 2026-07-19T22:13:31.557Z sha 30e077e :: needs real behavior proof before merge. :: none
• reviewed 2026-07-19T23:06:54.851Z sha b62143e :: needs real behavior proof before merge. :: none
• reviewed 2026-07-19T23:48:43.894Z sha b62143e :: needs real behavior proof before merge. :: none
• reviewed 2026-07-20T01:47:15.296Z sha df1a29b :: needs real behavior proof before merge. :: none

[giodl73-repo]

Implementation stack update:

• PR 1 foundation: feat: add localization runtime foundation openclaw#109456
• PR 2 runtime safety model: feat(localization): add runtime safety localization giodl73-repo/openclaw#116
• PR 3 process-scoped CLI localization: feat(cli): add process-scoped localization giodl73-repo/openclaw#117

PR 2 remains owner-gated for production Gateway emission, recipient-locale ownership, and non-English safety-copy attestation. PR 3 keeps successful structured output and literal commands, flags, identifiers, paths, versions, refs, and upstream diagnostics unchanged.

[giodl73-repo]

@clawsweeper re-review

RFC 0024 now includes the projected 44-entry owner-slice registry at exact head 0765058. The 44 entries are an editable source-audit decomposition—not a fixed PR count, acceptance gate, or runtime registry—and the RFC/spec sidecars now share that boundary model.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/29888635443
• Updated: 2026-07-22T03:31:14.226Z

[giodl73-repo]

@clawsweeper re-review

RFC head 2327361 clarifies that process locale applies only to owner-approved human CLI/TUI prose, never structured output or protocol values, and that explicit-only surfaces may omit platform inputs.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/29975111652
• Updated: 2026-07-23T02:43:31.237Z

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/29979046588
• Updated: 2026-07-23T04:14:47.001Z

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: RFC 0024: Localization Runtime and Product Coverage This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

[giodl73-repo]

Acceptance update: Patrick confirmed in Discord that the clarified RFC and rollout model “all makes sense” with a 👍 reaction. Recording that as the product-direction approval requested by the prior review—not as a GitHub review. RFC 0024 is now marked accepted and links implementation tracker openclaw/openclaw#113105 at exact head 267e575a67e74c6181438a74ae6199e7e3313168.