fix(docs/i18n): fix MDX compilation errors causing Cloudflare Pages failure#5460
Conversation
Three systematic bugs found in the i18n batch-2 translation (2026-05-07): 1. architecture.mdx: D2 lifecycle diagram truncated mid-block, footer merged 2. quick-start/installation.mdx: </TabItem>#### heading merged, unclosed Tabs/Steps 3. getting-started/your-first-app.mdx: :::tip admonition merged onto previous line 4. zh-tw/index.mdx: bare < before digit treated as invalid JSX All 7 locales (de, fr, ja, ko, pt, ru, zh-tw) affected. Local build verified: astro build exits 0, 1342 pages built.
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThis PR updates localized MDX docs: extends architecture pages (lifecycle, hooks, build, dev/prod, memory, security), expands quick-start npm installation tabs for macOS/Linux, and reformats Pro Tip callouts in getting-started pages. ChangesLocalized Documentation Updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/src/content/docs/de/quick-start/installation.mdx`:
- Around line 360-363: The code block contains German text that must stay in
English; update the fenced code block in installation.mdx replacing "❌
webkit2gtk nicht gefunden" with "❌ webkit2gtk not found" and "Installation mit:"
with "Install with:" so the shell instruction ("sudo apt install
libwebkit2gtk-4.1-dev") remains unchanged and the code block matches the
original English source.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: c8079e3e-5b31-4ca3-9107-15748d93283c
📒 Files selected for processing (3)
docs/src/content/docs/de/concepts/architecture.mdxdocs/src/content/docs/de/getting-started/your-first-app.mdxdocs/src/content/docs/de/quick-start/installation.mdx
| ``` | ||
| ❌ webkit2gtk nicht gefunden | ||
| Installation mit: sudo apt install libwebkit2gtk-4.1-dev | ||
| ``` |
There was a problem hiding this comment.
Code block contains German text—should remain in English.
The example output in this code block contains German translations ("webkit2gtk nicht gefunden" and "Installation mit:"), but code blocks must remain in their original English form across all locale MDX files.
📝 Proposed fix to restore English text
-❌ webkit2gtk nicht gefunden
- Installation mit: sudo apt install libwebkit2gtk-4.1-dev
+❌ webkit2gtk not found
- Install with: sudo apt install libwebkit2gtk-4.1-dev
As per coding guidelines: "For Wails documentation i18n/translation PRs, do not translate any text inside code blocks in MDX files. This includes fenced code blocks (```), embedded code/shell commands, and d2 diagram source text such as labels. Code block contents must remain exactly in their original English form across all locale MDX files."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/src/content/docs/de/quick-start/installation.mdx` around lines 360 -
363, The code block contains German text that must stay in English; update the
fenced code block in installation.mdx replacing "❌ webkit2gtk nicht gefunden"
with "❌ webkit2gtk not found" and "Installation mit:" with "Install with:" so
the shell instruction ("sudo apt install libwebkit2gtk-4.1-dev") remains
unchanged and the code block matches the original English source.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/src/content/docs/pt/quick-start/installation.mdx`:
- Line 14: In the Portuguese quick-start MDX file, revert translated
shell-comment lines inside fenced code blocks back to English: change "# Instale
o Go 1.25+ e depois:" to "# Install Go 1.25+ then:", change both occurrences of
"# Deve mostrar 1.25+" to "# Should show 1.25+", change "# Recarregar" to "#
Reload", and change "# ou ~/.bashrc" to "# or ~/.bashrc"; ensure these
replacements are made within the code block content (not prose) so all comments
in installation.mdx remain in original English across the file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: be8991dc-e101-4e1e-bae0-6067c5352c0b
📒 Files selected for processing (3)
docs/src/content/docs/pt/concepts/architecture.mdxdocs/src/content/docs/pt/getting-started/your-first-app.mdxdocs/src/content/docs/pt/quick-start/installation.mdx
| :::tip[TL;DR - Para desenvolvedores experientes] | ||
| ```bash | ||
| # Instale o Go 1.25+, depois: | ||
| # Instale o Go 1.25+ e depois: |
There was a problem hiding this comment.
Remove Portuguese translations from code block comments.
Shell command comments inside fenced code blocks must remain in English. The following lines contain translated comments that should be reverted to English:
- Line 14:
# Instale o Go 1.25+ e depois:→ should be# Install Go 1.25+ then: - Line 36:
# Deve mostrar 1.25+→ should be# Should show 1.25+ - Line 59:
# Deve mostrar 1.25+→ should be# Should show 1.25+ - Line 93:
# Recarregar→ should be# Reload - Line 292:
# Ubuntu/Debian→ should remain# Ubuntu/Debian(already English, OK) - Line 297:
# Fedora→ should remain# Fedora(already English, OK) - Line 298:
# Arch→ should remain# Arch(already English, OK) - Line 345:
# ou ~/.bashrc→ should be# or ~/.bashrc
As per coding guidelines, code block contents (including comments) must remain in their original English form across all locale MDX files to maintain consistency.
Proposed fix
-# Instale o Go 1.25+ e depois:
+# Install Go 1.25+ then:
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
wails3 doctor # Verificar instalação-go version # Deve mostrar 1.25+
+go version # Should show 1.25+-source ~/.bashrc # Recarregar
+source ~/.bashrc # Reload-source ~/.zshrc # ou ~/.bashrc
+source ~/.zshrc # or ~/.bashrcAlso applies to: 36-36, 59-59, 93-93, 292-292, 297-297, 298-298, 345-345
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/src/content/docs/pt/quick-start/installation.mdx` at line 14, In the
Portuguese quick-start MDX file, revert translated shell-comment lines inside
fenced code blocks back to English: change "# Instale o Go 1.25+ e depois:" to
"# Install Go 1.25+ then:", change both occurrences of "# Deve mostrar 1.25+" to
"# Should show 1.25+", change "# Recarregar" to "# Reload", and change "# ou
~/.bashrc" to "# or ~/.bashrc"; ensure these replacements are made within the
code block content (not prose) so all comments in installation.mdx remain in
original English across the file.
Master commit 1c2ec6a (feat(linux): flip GTK4 + WebKitGTK 6.0 to the default build) reorganised linux_cgo.go/linux_cgo_gtk3.go: GTK4 is now the default build path. Conflict resolutions: - linux_cgo.go: use master (GTK4 default, already has undo/redo fix) - docs/*: use master (translated content from fix(docs/i18n) #5460) GTK3 path (linux_cgo_gtk3.go) still needs undo/redo fix — addressed in the following commit.
Problem
The i18n batch-2 translations (committed 2026-05-07) introduced four categories of MDX compilation errors across all 7 translated locales. This causes
astro buildto exit 1, which fails the Cloudflare Pages: wails-v3-site check on all PRs.Root Cause
The translation pipeline merged content that should be on separate lines. Three files per locale are affected:
Bug 1 —
concepts/architecture.mdx(all 7 locales)D2 lifecycle diagram truncated at line 327;
Save: "Save State" {---(diagram close{...}merged with---footer separator).Fix: Restore complete D2 diagram close + missing Build Process/Dev vs Prod/Memory/Security/Next Steps sections.
Bug 2 —
quick-start/installation.mdx(all 7 locales)</TabItem>#### headingon same line — unclosed<Tabs>/<Steps>block.Fix: Add missing macOS/Linux npm TabItems, close Tabs/Steps, add Troubleshooting section.
Bug 3 —
getting-started/your-first-app.mdx(all 7 locales)[sentence].:::tip[...]merged on one line — tip admonition outside<Steps>list item.Fix: Separate
:::tiponto its own line with 4-space indent.Bug 4 —
zh-tw/index.mdxBare
<0.5— invalid MDX JSX before digit.Fix: Escape as
<0.5.Verification
Local build on fix branch:
astro buildexits 0, 1342 pages built.CC @leaanthony
Summary by CodeRabbit