Skip to content

docs-i18n: chunk raw doc translation#62969

Merged
hxy91819 merged 21 commits into
openclaw:mainfrom
hxy91819:codex/i18n-chunked-raw
Apr 9, 2026
Merged

docs-i18n: chunk raw doc translation#62969
hxy91819 merged 21 commits into
openclaw:mainfrom
hxy91819:codex/i18n-chunked-raw

Conversation

@hxy91819

@hxy91819 hxy91819 commented Apr 8, 2026

Copy link
Copy Markdown
Member

Summary

  • switch docs-i18n doc mode from one-shot whole-body raw translation to chunked raw translation with per-chunk structure validation and recursive split fallback
  • reject tagged doc outputs that omit the closing </body> tag instead of accepting truncated EOF bodies
  • harden docs-i18n against wrapper leakage, terminated Pi sessions, oversized chunk prompts, and component-heavy leaf-block drift without changing the default production openai/gpt-5.4 path

Why

  • the previous deploy failures were caused by truncated translated docs being accepted and written to disk
  • the AST-style prototype reduced tag loss but introduced too many extraction and coverage bugs for mixed MDX docs
  • this version stays closer to the original successful whole-doc translation path while reducing long-document failure risk by validating and recursively shrinking only the failing chunks

Compatibility

  • the small Pi provider/model refactor was added so local validation could exercise custom OpenAI-compatible providers such as Gemini/GLM through Pi
  • the default production path remains compatible: when docs-i18n runs with the built-in openai provider and gpt-5.4 model, it still passes --provider openai --model gpt-5.4
  • the new provider/model-ref path only changes behavior for custom providers, explicit provider-prefixed model refs, or runs that inject a custom PI_CODING_AGENT_DIR

Validation

  • cd scripts/docs-i18n && go test ./...
  • standalone reruns passed for previously broken pages:
    • docs/help/troubleshooting.md
    • docs/help/faq.md
    • docs/gateway/configuration-reference.md
    • docs/install/fly.md
    • docs/install/node.md
  • targeted high-risk reruns passed:
    • 5-page batch: docs/help/faq.md, docs/gateway/configuration-reference.md, docs/install/fly.md, docs/install/installer.md, docs/plugins/sdk-provider-plugins.md
    • 9-page expansion: docs/index.md, docs/channels/discord.md, docs/gateway/index.md, docs/gateway/openai-http-api.md, docs/plugins/bundles.md, docs/plugins/sdk-overview.md, docs/plugins/building-plugins.md, docs/plugins/sdk-channel-plugins.md, docs/reference/wizard.md
    • 10-page expansion: docs/install/azure.md, docs/install/gcp.md, docs/install/migrating.md, docs/install/raspberry-pi.md, docs/channels/telegram.md, docs/gateway/troubleshooting.md, docs/gateway/authentication.md, docs/plugins/sdk-runtime.md, docs/plugins/sdk-entrypoints.md, docs/reference/token-use.md
    • 13-page expansion: docs/concepts/model-providers.md, docs/concepts/oauth.md, docs/gateway/configuration-examples.md, docs/gateway/doctor.md, docs/help/environment.md, docs/help/testing.md, docs/providers/anthropic.md, docs/providers/openai.md, docs/reference/api-usage-costs.md, docs/reference/test.md, docs/tools/media-overview.md, docs/tools/music-generation.md, docs/tools/video-generation.md
  • final non-full dry run passed on 28 representative high-risk pages with processed=28 skipped=0
  • output scans on the rerun sets found no leaked protocol wrappers or frontmatter markers in generated localized pages (<frontmatter>, </frontmatter>, <body>, </body>, [[[FM_*]]])

Notes

  • this PR is intentionally limited to docs-i18n translation-path hardening; local preview/docs.json cleanup debugging stayed out of scope
  • the remaining content-level warnings are model-quality issues, not structure-corruption failures

@openclaw-barnacle openclaw-barnacle Bot added scripts Repository scripts size: L maintainer Maintainer-authored PR labels Apr 8, 2026
@hxy91819
hxy91819 marked this pull request as ready for review April 8, 2026 06:18
@hxy91819

hxy91819 commented Apr 8, 2026

Copy link
Copy Markdown
Member Author

Added one follow-up fix after the larger 15-page sample run exposed a remaining blocker in docs/gateway/configuration-reference.md.

What changed:

  • add a conservative leaf-chunk fallback in doc_chunked_raw.go: when recursive chunk splitting reaches a single block with no component tags and no code fences, retry through the masked Translate path instead of failing the whole page on a raw-translation hallucinated tag set
  • add a regression test in doc_mode_test.go that reproduces this exact failure mode

Validation:

  • cd scripts/docs-i18n && go test ./...
  • reran docs/gateway/configuration-reference.md locally with gemini-3-flash-preview; the page now completes successfully end-to-end instead of failing at the old chunk-011aaaa / leaf-chunk path

@hxy91819
hxy91819 force-pushed the codex/i18n-chunked-raw branch from fdc0b0c to cd8e860 Compare April 8, 2026 08:40

beordle commented Apr 8, 2026

Copy link
Copy Markdown

Follow-up: added a narrow runtime retry for terminated Pi sessions in scripts/docs-i18n/translator.go.

What changed:

  • PiTranslator now recreates the Pi client once when a request fails with a terminated/error session (pi error: terminated, stopReason=error, closed event stream/process).
  • Added regression coverage in scripts/docs-i18n/translator_test.go.

Validation:

  • cd scripts/docs-i18n && go test ./...
  • Gemini smoke: install/node.md completed successfully after the earlier frontmatter terminated failure.
  • Gemini smoke: install/node.md + plugins/bundles.md completed successfully in parallel.
  • Checked the generated outputs for protocol wrapper leakage (<frontmatter>, <body>, [[[FM_*]]]) and found none in those smoke outputs.

Latest commit on this branch: 12c4ca6b80.

@hxy91819

hxy91819 commented Apr 9, 2026

Copy link
Copy Markdown
Member Author

@greptile-apps review

@hxy91819

hxy91819 commented Apr 9, 2026

Copy link
Copy Markdown
Member Author

@codex review

@greptile-apps

greptile-apps Bot commented Apr 9, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR replaces the single-shot whole-document raw translation path with a chunked approach: the body is split into paragraph-level blocks, grouped by byte budget, translated chunk-by-chunk with per-chunk structural validation (code fence counts, component tag counts, protocol token leakage), and recursively bisected on failure. A leaf-block masked fallback (Translate with placeholder masking) handles single-block component-tag drift. parseTaggedDocument now rejects truncated outputs that are missing the closing </body> tag, which was the root cause of the prior deploy failures. The Pi client gains restart-on-termination support and a TranslateRaw path; provider/model routing is refactored for custom OpenAI-compatible providers.

Confidence Score: 5/5

Safe to merge — all remaining findings are P2 style/edge-case items that do not affect the default production path.

Both findings are P2: dead code (applyComponentLine/popComponent) and an env-var interaction edge case (OPENCLAW_DOCS_I18N_PI_OMIT_PROVIDER + built-in provider without agent dir) that the PR author explicitly says is outside the declared use cases. The default openai/gpt-5.4 production path is unaffected, structural validation is well-tested across many scenarios, and the truncation bug that caused prior deploy failures is correctly fixed.

No files require special attention for merge readiness. util.go has the env-var edge case worth a follow-up cleanup.

Vulnerabilities

No security concerns identified. The new code handles untrusted model output safely: protocol token leakage is validated and rejected, body extraction from wrapped responses uses a strict parser, and the materialized Pi runtime installs into a user-cache directory with appropriate permissions (0o700).

Prompt To Fix All With AI
This is a comment left during a code review.
Path: scripts/docs-i18n/doc_chunked_raw.go
Line: 317-349

Comment:
**Dead code: `applyComponentLine` and `popComponent` are never called**

These two functions are only referenced by each other — `applyComponentLine` calls `popComponent`, but nothing in the codebase calls `applyComponentLine`. The Go compiler accepts unexported dead code, but it will fail `go vet`/linting in stricter configurations and adds confusion about whether the block-tracking stack model is still in use. If they are kept for a planned follow-up, a brief comment would clarify intent; otherwise they should be removed.

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

---

This is a comment left during a code review.
Path: scripts/docs-i18n/util.go
Line: 81-113

Comment:
**`OPENCLAW_DOCS_I18N_PI_OMIT_PROVIDER` + `docsPiModelRef()` produces a broken Pi invocation for built-in providers**

`docsPiModelRef()` internally calls `docsPiProviderArg()` to decide whether to include a provider prefix. When `OPENCLAW_DOCS_I18N_PI_OMIT_PROVIDER=1` is set with a built-in provider (e.g. `openai`) and no `PI_CODING_AGENT_DIR` override:

- `docsPiProviderArg()` still returns `"openai"` (the omit flag is not consulted there)
- `docsPiModelRef()` sees `docsPiProviderArg() != ""` → returns bare `"gpt-5.4"` (no prefix)
- In `startDocsPiClient`, `!docsPiOmitProvider()` suppresses `--provider openai`
- Pi is invoked as `--model gpt-5.4` without a provider, which it cannot resolve

For all the declared use-cases (custom provider, explicit `provider/model` ref, custom `PI_CODING_AGENT_DIR`) `docsPiProviderArg()` already returns `""`, so `OPENCLAW_DOCS_I18N_PI_OMIT_PROVIDER` is a no-op in practice. Documenting this restriction or adding a guard in `docsPiModelRef()` that checks `docsPiOmitProvider()` would prevent a confusing failure for anyone who sets the env var with a built-in provider configuration.

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

Reviews (1): Last reviewed commit: "Docs i18n: harden component leaf fallbac..." | Re-trigger Greptile

Comment thread scripts/docs-i18n/doc_chunked_raw.go Outdated
Comment thread scripts/docs-i18n/util.go

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 79afb532f0

ℹ️ 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".

Comment thread scripts/docs-i18n/translator.go
@hxy91819
hxy91819 force-pushed the codex/i18n-chunked-raw branch from 79afb53 to 35f1b5e Compare April 9, 2026 11:30

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 35f1b5e02c

ℹ️ 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".

Comment thread scripts/docs-i18n/doc_chunked_raw.go Outdated
Comment thread scripts/docs-i18n/util.go

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 098e31ab21

ℹ️ 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".

Comment thread scripts/docs-i18n/doc_chunked_raw.go
Comment thread scripts/docs-i18n/translator.go

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4bc5ab4238

ℹ️ 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".

Comment thread scripts/docs-i18n/doc_chunked_raw.go Outdated
Comment thread scripts/docs-i18n/doc_chunked_raw.go
Comment thread scripts/docs-i18n/pi_rpc_client.go Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 35cd4f8868

ℹ️ 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".

Comment thread scripts/docs-i18n/doc_chunked_raw.go Outdated
Comment thread scripts/docs-i18n/process.go

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d91c790e1f

ℹ️ 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".

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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5be46c96fd

ℹ️ 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".

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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1fef456187

ℹ️ 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".

Comment thread scripts/docs-i18n/doc_chunked_raw.go
@hxy91819

hxy91819 commented Apr 9, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9ea756da48

ℹ️ 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".

Comment thread scripts/docs-i18n/doc_mode.go Outdated
@hxy91819

hxy91819 commented Apr 9, 2026

Copy link
Copy Markdown
Member Author

@codex review

@hxy91819

hxy91819 commented Apr 9, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fcdcb82c2e

ℹ️ 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".

Comment on lines +245 to +249
if !strings.HasPrefix(lower, bodyStartLower) || !strings.HasSuffix(lower, bodyEndLower) {
return "", false
}
body := text[len(bodyTagStart) : len(text)-len(bodyTagEnd)]
bodyLower := lower[len(bodyTagStart) : len(lower)-len(bodyTagEnd)]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Reject ambiguous body-only wrapper unwrapping

This unwrapping logic treats any text that starts with <body> and ends with </body> as a valid wrapper, even when the final </body> token is part of translated content rather than a real closing tag. In a truncated model response like <body>... literal </body> (no actual wrapper close), sanitizeDocChunkProtocolWrappers will strip the outer tags and accept a truncated chunk, silently dropping the trailing literal token instead of forcing a retry/error. That can corrupt generated docs for pages that mention </body> literally.

Useful? React with 👍 / 👎.

@hxy91819
hxy91819 force-pushed the codex/i18n-chunked-raw branch from fcdcb82 to 6a16d66 Compare April 9, 2026 15:20
@hxy91819
hxy91819 merged commit 06dea26 into openclaw:main Apr 9, 2026
8 checks passed
@hxy91819

hxy91819 commented Apr 9, 2026

Copy link
Copy Markdown
Member Author

Merged via squash.

Thanks @hxy91819!

@hxy91819
hxy91819 deleted the codex/i18n-chunked-raw branch April 9, 2026 15:22

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6a16d66486

ℹ️ 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".


current.WriteString(line)
if fenceDelimiter != "" {
if lineDelimiter != "" && lineDelimiter[0] == fenceDelimiter[0] && len(lineDelimiter) >= len(fenceDelimiter) && isClosingFenceLine(line, fenceDelimiter) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Accept longer closing fences when splitting doc sections

splitDocBlockSections treats a fence as closed only when isClosingFenceLine matches the original opener length exactly, so valid Markdown closers with more fence characters (for example opening with ``` and closing with ````) are not recognized. In that case fenceDelimiter stays open through the rest of the block, and retry planning falls back to non-fence-aware splits that can cut fenced content into invalid chunks and fail translation/validation for otherwise valid docs.

Useful? React with 👍 / 👎.

steipete pushed a commit that referenced this pull request Apr 10, 2026
Merged via squash.

Prepared head SHA: 6a16d66
Co-authored-by: hxy91819 <[email protected]>
Co-authored-by: hxy91819 <[email protected]>
Reviewed-by: @hxy91819
lovewanwan pushed a commit to lovewanwan/openclaw that referenced this pull request Apr 28, 2026
Merged via squash.

Prepared head SHA: 6a16d66
Co-authored-by: hxy91819 <[email protected]>
Co-authored-by: hxy91819 <[email protected]>
Reviewed-by: @hxy91819
ogt-redknie pushed a commit to ogt-redknie/OPENX that referenced this pull request May 2, 2026
Merged via squash.

Prepared head SHA: 6a16d66
Co-authored-by: hxy91819 <[email protected]>
Co-authored-by: hxy91819 <[email protected]>
Reviewed-by: @hxy91819
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 9, 2026
Merged via squash.

Prepared head SHA: 6a16d66
Co-authored-by: hxy91819 <[email protected]>
Co-authored-by: hxy91819 <[email protected]>
Reviewed-by: @hxy91819
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 24, 2026
Merged via squash.

Prepared head SHA: 6a16d66
Co-authored-by: hxy91819 <[email protected]>
Co-authored-by: hxy91819 <[email protected]>
Reviewed-by: @hxy91819
jameslcowan pushed a commit to jameslcowan/openclaw that referenced this pull request Jun 2, 2026
Merged via squash.

Prepared head SHA: 6a16d66
Co-authored-by: hxy91819 <[email protected]>
Co-authored-by: hxy91819 <[email protected]>
Reviewed-by: @hxy91819
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

maintainer Maintainer-authored PR scripts Repository scripts size: XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants