docs: localize fumadocs' accessible names, mark English page-tree entries, zh-Hant 404, Open-in links follow the page shown

[objectstack-fleet]

Fixes #305

Locale pages still announced fumadocs' built-in English accessible names, named untranslated pages in English with no language marked, served an English 404 to Traditional Chinese readers, and sent "Open in ChatGPT / Claude" on a translated page to the English Markdown. This PR fixes all four. Same defect family as #298, and built on its lib/ui-text and its fallback detection.

What changed

1. Accessible names come from lib/ui-text in every locale. fumadocs-ui 16.8.12 hard-codes nine names as English literals, outside its Translations API: Open Search, Toggle Theme, Open Sidebar, Collapse Sidebar, Copy Anchor Link, Copy Text, Copied Text, Toggle Menu, and Radix's default "Main" on the legal pages' header. patches/fumadocs-ui@16.8.12.patch (pnpm patchedDependencies, next to the existing fumadocs-core pin) makes each component read its name from the i18n context it already reads for text.search. The default is the old literal, so English is unchanged.

• Eight of the keys are a backport of upstream's own fix: fumadocs-ui 16.9.0 ships the same key names (searchOpen, themeToggle, sidebarOpen, sidebarCollapse, headingCopyAnchor, codeBlockCopy, codeBlockCopied, menuToggle) with the same defaults. I checked this by unpacking the published tarball.
• navMain is the one key upstream does not have. It was still unlocalized in 16.16.2.
• Why a patch and not slot overrides: I checked each name against the DocsLayout and HomeLayout slot API first. None can be reached everywhere it renders without re-implementing the component that renders it. For example, the collapsed-sidebar panel imports SearchTrigger directly, and both "Collapse Sidebar" buttons and the drawer's "Open Sidebar" live inside the Sidebar slot, which is a fork of about 200 lines. The patch header has the analysis name by name, plus when the patch can be deleted (on upgrading to 16.9.0 or later).
• lib/ui-text.ts adds the nine strings, and fumadocsTranslations() passes them to RootProvider. The six translated tables gain them, and ui-text/zh-Hant.json is regenerated by gen-zh-hant.

2. Untranslated page-tree entries carry lang="en". app/[lang]/docs/layout.tsx transforms the locale's page tree before handing it to DocsLayout. That one transform reaches the sidebar, the breadcrumb and the previous/next footer.

• Each page entry with no source file in the locale gets its name and description wrapped in span lang="en". The footer shows the description, which was English too.
• Detection uses the same translatedLocales function the docs page uses for its body (290 English-fallback locale URLs render English under lang="xx" with no notice, and the docs chrome (search, TOC, Copy Markdown, language picker) is English in every locale #298), so the chrome and the body cannot disagree.
• Folder names use the same file-identity rule on meta.LOCALE.json. No folder is affected today, because every folder has a translated meta title.
• The llms routes read the English tree directly and are untouched.

3. zh-Hant 404 text. The 404 copy moved from a constant in app/not-found.tsx into lib/ui-text (notFound). The Traditional string is now generated from the Simplified one by gen-zh-hant, and --check covers it like every other zh-Hant string. The exact-key table type makes every locale carry the string.

4. "Open in ChatGPT / Claude" follows the page shown. I chose to point the assistant at the shown locale's content, matching #298's Copy Markdown rule:

• English pages and fallbacks still send the English .mdx, which is the page on screen.
• A real translation sends the translated page's own URL (/ja/docs/...).
• Inlining the locale Markdown into the prompt was measured and rejected. Across the 230 locale pages, the query string runs from 2089 to 25630 characters, with 165 over 8 KiB, and neither assistant publishes a URL limit. The .mdx surface stays English-only, as AGENTS.md rule 1 and check-locale-surface require.

Branch and rebase

• Pushed head: 41a1994 on claude/pm-dispatch-objectos-ju9td1, a fast-forward with no force. It starts at the remote branch head 5e666c3 (fix(docs): run the awaited fumadocs-mdx write after next typegen in type-check #313), merges origin/main @ 92a12d2 (fix(docs): run the awaited fumadocs-mdx write after next typegen in type-check #313, which is CI type-check can fail with TS2306 ".source/server.ts is not a module": next typegen exits while fumadocs-mdx's un-awaited regeneration is still writing .source #311; after the merge the diff against main is empty), and cherry-picks 4da46c5. git diff origin/main 41a1994 is byte-identical to git diff 5d2f837 4da46c5, so CI type-check can fail with TS2306 ".source/server.ts is not a module": next typegen exits while fumadocs-mdx's un-awaited regeneration is still writing .source #311's one-line type-check reorder does not interact with this diff. CI re-runs every gate on the pushed head.
• Branch: staged/issue-305, one commit 4da46c5, on top of main at 5d2f837 (docs: contrast, phone table affordance, FAQ headings, title-weighted per-locale search, consistency pass (#301) #310, which is Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301; docs: SEO titles for the 67 English pages whose title tag was two words or fewer #309, which is Author SEO titles for the 42 English pages whose title tag is a single word #167, sits below it).
• Rebase: git rebase origin/main from the first tip 1f5ea81 (cut from cec227a). It applied with no conflicts, and git range-diff reports the commit patch-identical (1f5ea81 = 4da46c5). Nothing needed resolving:
  • Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301's logo link, www icon link, global.css, mdx-components.tsx, source.config.ts, the search route, smoke-docs.mjs and the glossary are files this PR does not touch.
  • Author SEO titles for the 42 English pages whose title tag is a single word #167's seoTitle lines are content this PR does not touch.
• Semantic interactions checked after the rebase:
  • Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301 points the logo at /LOCALE/docs. The built-HTML scanner first read that link as a sidebar page entry (79 per locale, text "ObjectOS"). I narrowed it to page-tree items (a[data-active]). The sidebar count then returns to exactly the pre-rebase 1166 per locale, and the narrowed scanner still reproduces the main baseline exactly (1375–1387 names, 687/920 unmarked).
  • Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301's www link is a host name, which is exempt like the brand names.
  • Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301 removed some locale pages (flows), so locales now have 30 more untranslated tree entries. All of them are marked.
• The CI type-check can fail with TS2306 ".source/server.ts is not a module": next typegen exits while fumadocs-mdx's un-awaited regeneration is still writing .source #311 type-check race (TS2306 on .source/server.ts) did not occur locally. Both type-check runs were green on the first try.

Measurements (built HTML, JS off)

	main cec227a	this PR on cec227a (1f5ea81)	this PR on 5d2f837 (4da46c5)
English chrome names on locale pages (per locale, 82 pages)	1375–1387	0	0
untranslated page-tree entries without lang="en", zh-Hans / zh-Hant	687	0 (of 687)	0 (of 717)
the same, ja / de / es / fr / ko (each)	920	0 (of 920)	0 (of 950)
translated entries wrongly marked lang="en"	0	0	0
zh-Hant 404 text	English	找不到此頁面。	找不到此頁面。

• Oracle: "untranslated" is read from the content tree (whether a SLUG.LOCALE.mdx file exists), not from the app's own detection.
• Coverage: all 7 locales × 82 pages for names, and every locale docs page for the tree. Folder names and breadcrumb items are all translated, with 0 English among 639 folder buttons and 95 breadcrumb items per locale, on both tips.
• RSC payload on /de/docs/operate/backup, counting lang="en" spans:
  • 4da46c5: 117 = 55 names + 55 descriptions + 7 TOC items from 290 English-fallback locale URLs render English under lang="xx" with no notice, and the docs chrome (search, TOC, Copy Markdown, language picker) is English in every locale #298.
  • 1f5ea81: 113 = 53 + 53 + 7.
  • zh-Hans: 69 = 31 + 31 + 7.
  • Each count matches exactly.
• Hydrated pages: checked in a browser on the Worker preview (opennextjs-cloudflare preview) at 4da46c5, for every locale, on one fallback and one translated page:
  • 0 English names, including after collapsing the sidebar, opening the drawer and the search dialog, and copying a code block ("Text kopiert" / "已复制文本").
  • Tree marks correct, and 0 hydration errors.
  • Open-in prompts read .../docs/operate/backup.mdx on the fallback and .../LOCALE/docs/build/data on the translation.
  • The 404 shows the locale text with lang set in all 8 locales.
  • The legal header on /de/privacy announces Hauptnavigation, Suche öffnen, Menü ein- oder ausblenden, Design wechseln and Sprache wählen.
• English is unchanged (measured against cec227a): the served HTML outside the RSC payload and asset hashes matches main's byte for byte on /docs/build/data and /privacy. On /docs/operate/backup the only difference is one shiki token colour inside a code block (see Acceptance notes).

Verification at 4da46c5 (rebased tip)

• pnpm install --frozen-lockfile: exit 0
• pnpm turbo run type-check --continue --force: 1 successful
• pnpm turbo run build --force (NEXT_PRIVATE_STANDALONE=true): 1 successful, 1038/1038 static pages
• pnpm turbo run test --force: ✓ 10 self-test(s) passed
• gen-zh-hant --check: ✓ 60 generated file(s) match the zh-Hans sources byte for byte
• check-locale-surface, check-positioning: ✓
• check-search-locales: ✓ all 8 locales answer 200, find "permissions", find every own page by its title within the first 3 pages, and find nothing for a nonce
• translations, with the workflow argv (git diff --name-status --no-renames origin/main...HEAD, 15 files):
  • Ownership, actor hotlong, bot login unset: reports, exit 0.
  • Ownership, actor hotlong, bot login set: ✓ no translation artifacts touched.
  • Control, actor = the bot login: ✗ "translation PRs may only touch translation artifacts", exit 1, as it should.
  • Freshness ✓; Output --files ✓ (256 pre-existing findings reported, from main's corpus; this diff touches no content); Output self-test ✓.
• check-node-floor (+ self-test) and the half-state sweeper self-test pass.
• Worker: opennextjs-cloudflare build --skipNextBuild plus wrangler deploy --dry-run gives Total Upload 47077.66 KiB, under the 61440 KiB budget.
• smoke-docs.mjs (Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301's version) against the local preview: ✓ 4 page(s) rendered, negative control demonstrated red, search answered in 8 locale(s) and found nothing for a nonce.
• Reverse check, at 1f5ea81 (the commit is patch-identical after the rebase):
  • Removing navMain from fumadocsTranslations() turns tsc red with TS2741 "Property 'navMain' is missing … required in type 'FumadocsTranslations'". Only the patched .d.ts requires that key.
  • Restored with git checkout HEAD: blob equals HEAD and git diff HEAD is empty.
• axe 4.14.0 ran on one fallback and one translated page per locale. It reports no violation this change introduces: every violation it lists also appears on the English page with the same node count.
  • color-contrast is down from 32–73 nodes per page at 1f5ea81 to 2–11 at 4da46c5, from Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301's contrast work.
  • Still pre-existing: landmark-one-main, region, svg-img-alt, landmark-unique, and label-content-name-mismatch on the language switcher.
  • valid-lang passes on the new lang attributes.

Screenshots (1440 and 390), re-taken at 4da46c5 because #301 changed the header:

• the zh-Hans fallback page sidebar and drawer, now showing Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301's globe and GitHub icons;
• the de search and sidebar triggers;
• the de legal-page header (new);
• the zh-Hant 404.

fumadocs draws no visual tooltip, so the de shots overlay each control's accessible name as a labelled "(aria-label)" annotation.

Acceptance notes

• Not filed: one shiki token (a ; in operate/backup's first code block) is coloured #032F62 on main's build and #24292E on this one, from identical content. This change does not touch highlighting. The evidence is two builds only.
• Not filed: the prompt sentence "Read URL, I want to ask questions about it." is English on every locale. Upstream 16.9.0 makes it a translation key (pageActionsOpenInLLMPrompt). Carrier: none.
• Out of scope, reported to the seat (same family, not this card's four items): /LOCALE/privacy and /LOCALE/terms on de, ja, es, fr, ko and zh-Hant render the English body inside html lang="LOCALE" with no lang="en" anywhere (0 on each page). zh-Hant gets English there rather than a generated Traditional version of the zh-Hans text.
• No CI gate in this PR pins the scans above. staged/issue-308 ("read the built pages for English chrome names and unmarked page-tree entries") is that gate's own card.

---

Generated by Claude Code