docs: legal pages mark their English fallback and get zh-Hant from zh-Hans; one main landmark

[objectstack-fleet]

Fixes #312

The legal pages /LOCALE/privacy and /LOCALE/terms now handle locales they are not written in correctly:

• de, ja, es, fr, ko: the English text is marked lang="en", and the 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 notice (ui-text notTranslated) appears above it in the page's own locale.
• zh-Hant: shows Traditional Chinese generated from the zh-Hans copy by gen-zh-hant, the same way as every other zh-Hant string.
• en and zh-Hans: the wording is unchanged.
• Every locale: the page's own wrapper is now an article instead of a second main nested in HomeLayout's main#nd-home-layout. This clears axe landmark-no-duplicate-main, landmark-main-is-top-level and landmark-unique, and nothing moves on screen.

What changed

• apps/docs/app/[lang]/{privacy,terms}/page.tsx
  • A locale missing from content gets the English entry, with lang="en" on the title, date, body and back link.
  • It also gets the 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 notice (Callout, role="note", data-untranslated-notice) in the route locale, placed before the English text.
  • The en entry is unchanged byte for byte, so check-positioning rule (c) still reads it.
  • en and zh-Hans render as before. The only change to their HTML is one new hrefLang="zh-Hant" alternate link.
  • Second commit: the page's wrapper element becomes article, with the same classes, because HomeLayout already renders main#nd-home-layout around the header and the page.
• apps/docs/app/[lang]/{privacy,terms}/zh-Hans.json (new): the zh-Hans entry, moved out of page.tsx with no change (deep-equal to the HEAD entry). It is JSON because the generator converts a data file, the same reason lib/ui-text/ is JSON.
• apps/docs/app/[lang]/{privacy,terms}/zh-Hant.json (new, generated):
  • Produced by gen-zh-hant (OpenCC s2twp).
  • contentLocales, hreflang, canonical and the sitemap pick up zh-Hant through the content keys, the mechanism Docs metadata: the index share card prints a 511-character description over its title, /privacy and /terms ship no metadata, and an internal MDX note leaks into llms-full.txt and Copy Markdown #299 set up.
  • On de, ja, es, fr and ko, hreflang lists en, zh-Hans, zh-Hant and x-default, and canonical stays the English URL.
• apps/docs/scripts/gen-zh-hant.mjs: the single ui-text pair becomes FIXED_PAIRS (ui-text, privacy, terms). As a result, --check covers the legal copy.
• .github/scripts/check-locale-surface.mjs
  • STATIC_PAGES lists zh-Hant.
  • Three new rules read the built legal pages. The English page's main-content text is the oracle.
    • legal-english-unmarked: an unlisted locale shows English text that does not resolve to en.
    • legal-translation-shows-english: a listed locale shows English text, or text marked English.
    • legal-page-unread: a page is missing, the oracle is empty, or an unlisted locale shows no English text.
  • Five self-test cases cover these rules, including the not-built case, which raises artifact-missing.
  • The reader skips the header and nav that HomeLayout puts inside its main element, and it skips script content. The fixture mirrors the real structure: HomeLayout's main holds the header and the page's article.

Branch and rebase

• Base: main 9d3ff08, which carries Docs chrome still speaks English inside localized pages: fumadocs' hard-coded aria-labels, English page-tree names without lang="en", no zh-Hant 404 copy #305 (cf449fa), Docs code samples the current @objectstack/spec refuses: the remaining view fragments in build/interface/views.mdx and the send_email flow action in build/automation/flows.mdx #307 (docs: make the views and flows code samples parse with @objectstack/spec 17.7.0 #315) and Docs accessibility baseline: no main landmark, the language switcher's name contradicts its text, an unnamed svg role=img, unnamed code regions — on every page in every locale #308 (docs: a main landmark, a switcher named by its text, code blocks off the landmark list, buttons that keep their own language, a localized Open-in prompt, and a CI rule for the locale chrome #317). The tip is e6bf746, two commits: 39b76e1 (lang and notice, zh-Hant, gate) and e6bf746 (article instead of a nested main).
• Rebased with git rebase --onto origin/main 4da46c5 staged/issue-312. The pre-rebase commits were 297882f and 85b6b4b.
• No conflicts, so no resolutions were needed: git applied every hunk in check-locale-surface.mjs on top of Docs accessibility baseline: no main landmark, the language switcher's name contradicts its text, an unnamed svg role=img, unnamed code regions — on every page in every locale #308's rule.
• git range-diff shows one context-only difference in commit 1: around collect's return line and evaluate's signature, which Docs accessibility baseline: no main landmark, the language switcher's name contradicts its text, an unnamed svg role=img, unnamed code regions — on every page in every locale #308 changed. Commit 2 is patch-identical (=).
• The merged gate keeps both cards' rules, readers and self-test cases:
  • Docs accessibility baseline: no main landmark, the language switcher's name contradicts its text, an unnamed svg role=img, unnamed code regions — on every page in every locale #308: english-chrome-name, the page-tree rules, its reader and its live control.
  • This card: the three legal-* rules, the legal… reader, legalFixturePages and 5 cases.
• The legal: null fixup is not needed and not applied. Docs accessibility baseline: no main landmark, the language switcher's name contradicts its text, an unnamed svg role=img, unnamed code regions — on every page in every locale #308's 42da2b1 makes its built-pages guard count docs pages only, and the merged self-test passes as-is, including ✓ docs pages not built fired [artifact-missing].
• The en and zh-Hans legal copy was re-proved unchanged against 9d3ff08.

Verification on the rebased tip (e6bf746, real --force build)

• pnpm install --frozen-lockfile: Lockfile is up to date, exit 0.
• pnpm turbo run type-check --continue --force: Tasks 1 successful, VERDICT command-exit 0.
• NEXT_PRIVATE_STANDALONE=true pnpm turbo run build --force: Generating static pages (1038/1038), Tasks 1 successful, VERDICT command-exit 0. There are 332 OG font-fetch proxy warnings, the same count as every earlier build.
• pnpm turbo run test --force: ✓ 10 self-test(s) passed, VERDICT command-exit 0.
• check-locale-surface: exit 0 with ✓ every advertised URL has a source file …, on a real build. Both cards' sections are present.
  • Legal table: wrong 0 on all 14 non-English pages, 12 or 14 text nodes on each fallback, sitemap 301/301.
  • Docs accessibility baseline: no main landmark, the language switcher's name contradicts its text, an unnamed svg role=img, unnamed code regions — on every page in every locale #308's built-pages table: 82 pages read per locale, 0 English chrome names, 0 unmarked untranslated entries, 0 translated entries marked English, live control fired.
• check-locale-surface --self-test: ✓ self-test: 48 case(s) over 25 rule(s) and 3 artifact(s).
• check-positioning ✓, check-search-locales ✓ (all 8 locales answer 200), and gen-zh-hant --check: ✓ zh-Hant: 62 generated file(s) match ….
• Translations, using the workflow argv. origin/main...HEAD is now only this card's 8 files.
  • Ownership with actor hotlong: unset exit 0; armed ✓ 8 file(s) changed, no translation artifacts touched.
  • Bot-actor control: ✗ translation PRs may only touch translation artifacts. (exit 1, as expected).
  • Freshness ✓, Output --self-test ✓, and Output --files: ✓ … (256 pre-existing finding(s) reported).
• check-node-floor and --self-test, check-half-states --self-test: all exit 0.
• Built-HTML legal check with JavaScript off: 16 of 16. Live legal check at 1440 and 390: 32 of 32, 0 console errors.
• axe 4.14.0 on /privacy and /terms in en, de and zh-Hant, at 1440 light, 1440 dark and 390 light (18 runs): 0 violations of any rule.
  • landmark-no-duplicate-main, landmark-main-is-top-level and landmark-unique are 0.
  • svg-img-alt is now 0 as well. Docs accessibility baseline: no main landmark, the language switcher's name contradicts its text, an unnamed svg role=img, unnamed code regions — on every page in every locale #308's patch makes the header GitHub icon aria-hidden, and the built /de/privacy has no svg role="img".
• Screenshots retaken: /de/privacy and /zh-Hant/terms at 1440 and 390, and looked at. The /de/privacy PNGs are byte-identical to the pre-rebase ones (sha256 ed1644f3e921…, 9f32ffbe995e…).

Verification before the rebase (on 4da46c5; HEAD then 85b6b4b)

The rebased tip is verified again in the section above. The measurements below were taken before the rebase. 85b6b4b differs from the built c3ad871 only in a comment reflow in check-locale-surface.mjs, so its app tree is byte-identical to the build measured here.

CI case, red before, green after. The committed gate was run against a fresh --force build of the base (4da46c5): ✗ locale surface: 14 finding(s).

• legal-english-unmarked ×10: ja, de, es, fr and ko, for both pages. "11 of the 11 English text node(s) de shows for privacy resolve to lang=de".
• legal-translation-shows-english ×2: zh-Hant, for both pages.
• missing-url ×2: the zh-Hant legal URLs are missing from the sitemap.

On this branch's build (c3ad871, the same app tree as HEAD) the gate exits 0 with ✓ every advertised URL has a source file …. The legal table shows wrong 0 on all 14 non-English pages, and the sitemap has 301 entries (301 expected).

Built-HTML check. Chromium parsed every built page with JavaScript off, and the DOM was asked which lang each text node resolves to (closest('[lang]')). All 16 pages (8 locales × 2) pass, on both the 297882f build and the c3ad871 build:

• de, ja, es, fr, ko: html lang is the route locale. There are 4 lang="en" elements in the content, and every English text node resolves to en. The notice is visible, matches ui-text notTranslated, and resolves to the route locale.
• zh-Hant: the text equals zh-Hant.json, and per-string s2twp(zh-Hans) equals zh-Hant.json. No English text, no lang="en". Canonical is the page's own zh-Hant URL.
• hreflang: exactly en, zh-Hans, zh-Hant, x-default on every page.

The same checks also passed against next start, with JavaScript on, at 1440 and 390: 32 of 32 on each build, and 0 console errors.

axe 4.14.0 on /privacy and /terms in en, de and zh-Hant, hydrated, at 1440 light, 1440 dark and 390 light (18 runs each side):

rule	before (297882f build)	after (c3ad871 build)
landmark-no-duplicate-main	18	0
landmark-main-is-top-level	18	0
landmark-unique	18	0
svg-img-alt (the header GitHub icon; 0 after the rebase onto #308)	12	12

• No rule appears after the change that was absent before.
• document.querySelectorAll('main') returns 2 before and 1 after.

Screenshots, before and after the article change: /de/privacy at 1440 and 390. The before and after PNGs are byte-identical (sha256 ed1644f3e921… at 1440, 9f32ffbe995e… at 390), so nothing moved, and both were looked at.

Screenshots (both widths looked at): /de/privacy and /zh-Hant/terms at 1440 and 390.

• /de/privacy: the German notice sits above the English policy.
• /zh-Hant/terms: 服務條款 / 許可 / 託管服務 / 返回首頁, and the header search reads 搜尋.

Reverse verification, run once against committed HEAD. Renaming back in privacy/zh-Hans.json makes tsc exit 2 with TS2339 (Property 'back' does not exist). The file was then restored byte-identical (blob 983f34dec0cc == HEAD, git diff HEAD empty).

Gate ablation. With the header and nav skip removed, the self-test turns red: the clean baseline fires legal-english-unmarked and legal-translation-shows-english on the brand text in the header. Restored byte-identical (blob 9183f0ddcd6e).

Gates (type-check, build and the post-build gates at c3ad871; turbo test, check-locale-surface and its self-test again at 85b6b4b)

• pnpm turbo run type-check --continue --force: Tasks 1 successful, VERDICT command-exit 0.
• NEXT_PRIVATE_STANDALONE=true pnpm turbo run build --force: Generating static pages (1038/1038), Tasks 1 successful, VERDICT command-exit 0. There are 332 OG font-fetch proxy warnings, the same count as the base build.
• pnpm turbo run test --force: ✓ 10 self-test(s) passed, VERDICT command-exit 0.
• check-locale-surface: exit 0 (line above). --self-test: ✓ self-test: 36 case(s) over 18 rule(s) and 3 artifact(s).
• check-positioning: ✓ positioning: 4 copies equal their constants; … the en entry of 2 legal pages.
• check-search-locales: ✓ search locales: all 8 locales answer 200 ….
• gen-zh-hant --check: ✓ zh-Hant: 62 generated file(s) match the zh-Hans sources byte for byte. (60 before this change, plus the 2 legal files.)
• Translations Ownership, using the workflow argv (git diff --name-status --no-renames origin/main...HEAD; origin/main is cf449fa, so the merge base is still 5d2f837 and the list has 23 files, Docs chrome still speaks English inside localized pages: fumadocs' hard-coded aria-labels, English page-tree names without lang="en", no zh-Hant 404 copy #305's included; after the rebase it is this card's 8), with actor hotlong:
  • Unset bot login: exit 0.
  • Armed: ✓ 23 file(s) changed, no translation artifacts touched.
  • Control with actor = bot: ✗ translation PRs may only touch translation artifacts. (exit 1, as expected).
  • This card's 8 files alone (4da46c5...HEAD), armed: ✓ 8 file(s) changed, no translation artifacts touched.
• Translations Freshness: ✓ translations gate passed.
• Translations Output: --self-test ✓. --files: ✓ translation output gate passed (256 pre-existing finding(s) reported).
• check-node-floor and --self-test, check-half-states --self-test: all exit 0.
• Not measured here, and left to CI: the Worker package, size budget and local-preview smoke. They were not in this card's gate list.

Acceptance notes

• check-locale-surface's final ✓ summary sentence (now Docs accessibility baseline: no main landmark, the language switcher's name contradicts its text, an unnamed svg role=img, unnamed code regions — on every page in every locale #308's wording) does not mention the legal rules. The legal result is printed in its own table. A follow-up could add a clause.
• The gate now has two small HTML readers: Docs accessibility baseline: no main landmark, the language switcher's name contradicts its text, an unnamed svg role=img, unnamed code regions — on every page in every locale #308's readHtml and this card's legalMainText. A follow-up could fold the legal rules onto readHtml.
• s2twp renders 账号 as 賬號 (Taiwan usage prefers 帳號). This is generated output and comes from the converter's vocabulary.

Pushed head

7c17974 on claude/pm-dispatch-objectos-ju9td1, a fast-forward with no force. It starts at the remote branch head fa2390f, merges origin/main @ 9d3ff08 (#317; after the merge the diff against main is empty), and cherry-picks 39b76e1 and e6bf746. git diff origin/main 7c17974 is byte-identical to git diff origin/main e6bf746.

---

Generated by Claude Code