Docs ships seven locales and the marketing site ships eight — `zh-Hant` is the missing one, and docs already has a comment waiting for it

[hotlong]

Blocked-by: #169

The reading

apps/docs/lib/i18n.ts:17 declares seven locales: en, zh-Hans, ja, de, es, fr, ko.

apps/docs/middleware.ts:30-33 maps Traditional Chinese browsers onto Simplified, with this comment:

Traditional variants fall back to Simplified until zh-Hant ships

So zh-TW and zh-HK readers are served Simplified today, by an explicitly temporary arrangement.

Meanwhile the marketing site — objectstack-ai/www.objectos.ai, which the maintainer attached to this session — ships eight locales including zh-Hant (src/lib/i18n.ts:3-5), and generates the Traditional set mechanically from the Simplified one. Its AGENTS.md documents the pipeline:

zh-Hant content is generated from zh-Hans with pnpm gen:zh-hant; do not hand-edit generated Traditional Chinese files

and its converter lives at src/lib/zhconvert.ts.

The condition that comment in middleware.ts is waiting on has therefore already been met next door. The generation path exists, is in production, and is owned by the same team.

Why this is a keyword card and not just a parity card

www.objectos.ai/AGENTS.md states as standing policy:

Localize for reach. Long-tail search and model coverage in ja/ko/de/es/fr is cheap reach that English-only competitors miss.

Traditional Chinese is the same trade, for Taiwan and Hong Kong, and it is cheaper here than any other locale on the list because it is derived rather than authored. Simplified and Traditional are not interchangeable in search: the query strings differ character-by-character, so a Simplified page does not rank for a Traditional query however good it is.

Why this is blocked on #169

#169 is rewriting how the locale surface is derived — sitemap entries and hreflang alternates will be emitted per real translated file rather than for all seven locales unconditionally. Adding an eighth locale before that lands would collide in lib/i18n.ts, lib/seo.ts and app/sitemap.ts, and would add an eighth row to exactly the over-advertisement problem #169 exists to fix. Do this after.

Known trap for whoever picks this up

Docs' Simplified coverage is 62 of 79 pages, not complete. Generating Traditional from Simplified inherits that gap exactly — you would ship zh-Hant at 62/79 on day one. That is acceptable if and only if #169 has already landed, because then the missing 17 simply are not advertised. Verify #169's behaviour is in place before generating, rather than assuming it.

Also confirm before starting: whether the docs site wants a generated-and-committed Traditional set (www's model) or on-the-fly conversion. www commits the generated files and gates hand-editing; copying that model is the low-surprise choice, but it roughly doubles the Chinese file count in content/docs.

Verification

• zh-TW and zh-HK browsers reach a Traditional path rather than being remapped to Simplified, and the legacy mapping in middleware.ts:30-33 is updated rather than left contradicting the new state.
• The temporary comment quoted above is removed once it is no longer true.
• Traditional pages declare the correct language (this depends on Every page in all seven locales declares lang="en" on the root html element #168 landing — check it has).

[hotlong]

Unblocked — #169 merged as 93a366c (PR #176). pm:blocked removed, back to pm:queue.

Re-verified the premise against the merged tree rather than just clearing the label, because the upstream merge could have changed this card's shape:

The known trap on this card is now satisfied, not merely survivable. The body warned that generating Traditional from Simplified inherits the 62-of-79 Simplified gap, and that this is acceptable if and only if #169 has landed. It has. translatedLocales() derives the advertised locale surface from the files that actually exist, so shipping zh-Hant at 62/79 advertises 62 — the missing 17 simply are not claimed. Before #169 the same move would have added a eighth row to the over-advertisement defect.

The mechanism generalises to an eighth locale for free. translatedLocales() iterates i18n.languages and filters by file identity, and languageAlternates() iterates the same list, so adding zh-Hant to lib/i18n.ts is picked up by both surfaces with no further change. That was not true of the pre-#169 code, which hardcoded the assumption that every locale had every page.

One thing got harder, and it is worth knowing before dispatch. languageAlternates(path, locales) now takes a required second argument, and translatedLocales() compares each locale's page.path against the English page's. Generated Traditional files must therefore be real files on disk with the zh-Hant suffix — a runtime conversion of the Simplified page would produce an identical page.path and be classified as a fallback, i.e. correctly not advertised. So the open question in the body ("generated-and-committed, www's model, or on-the-fly conversion?") is now settled by the mechanism: committed files, or the locale never appears in any sitemap entry or hreflang cluster. Worth stating in the dispatch so nobody discovers it by measurement.

Still gated on #168 for the language attribute, which merged as 8feb90d — so that dependency is also clear.

---

Generated by Claude Code

[hotlong]

Unblocked and dispatching. #169 landed, and so did #168, #180, #207, #209, #210 and #208. This is the last large card in the chain.

Claim: PM loop round 13
Session: session_01G5zjYc2BoFV2NjKBBapC7C
Branch: claude/issue-172-zh-hant
Worktree: objectos-issue-172
Domain: n/a (objectos carries no domain:* lanes)
Container and model: L, mode:subagent, model: opus
Clause-②: no
File surface: apps/docs/lib/i18n.ts, apps/docs/middleware.ts, apps/docs/app/[lang]/layout.tsx, apps/docs/package.json, the generation script you add, the generated content/docs/**/*.zh-Hant.mdx files, and — only if they turn out to hardcode the locale list rather than derive it — apps/docs/app/llms.txt/route.ts and .github/scripts/check-locale-surface.mjs. Anything beyond that: stop and report.

⚠️ llms.txt/route.ts was rewritten 20 minutes ago by #210 (7339119) and check-locale-surface.mjs by #208 (e8b2062). Base on current main and read both. #210's new wording states that the .mdx surface is English-only and warns in a comment that no gate reads that prose — do not clobber it while updating a locale list beside it.

Adjudicated: generate-and-commit, matching www. This is a mechanism argument, not a preference.

The card asks which model docs wants. Take www's — generated files committed, hand-editing gated — and the reason is not "low surprise":

check-locale-surface.mjs derives its oracle from content/docs/, and #169 made translatedLocales() discriminate a real translation from an inherited English fallback by the presence of a locale-suffixed source file. On-the-fly conversion produces no such files. So zh-Hant would be a locale the site accepts, renders and switches to — and never advertises in the sitemap or in a single hreflang alternate. Invisible to exactly the search engines this card exists to reach.

Generate-and-commit is the only option that achieves the card's stated purpose given how the surface is now derived. Do not spend time re-litigating it; do check that I have the mechanism right, and say so if I do not.

Verify #169's behaviour rather than assuming it

Simplified coverage is 62 of 79, so Traditional ships at 62/79 on day one. That is acceptable only because the 17 untranslated pages are not advertised. Measure that, do not infer it: after generating, confirm the sitemap and the hreflang sets carry zh-Hant for exactly the 62 and for none of the 17.

If that does not hold, stop — shipping 17 English pages advertised as Traditional would undo the largest single thing this run of cards fixed.

The dependency is a boundary

Report which conversion package you add and its exact version. It must be a build-time dependency whose output is committed. If anything about the approach needs a runtime dependency, stop and report — new runtime third-party dependencies are the maintainer's call, not mine and not yours.

www's converter is src/lib/zhconvert.ts in objectstack-ai/www.objectos.ai; read it before choosing. Matching what the sibling repo already runs in production is worth more than picking a library on its merits.

The rest

• middleware.ts:30-33 maps zh-TW and zh-HK onto Simplified with the comment "Traditional variants fall back to Simplified until zh-Hant ships". Update the mapping and delete the comment — it becomes false the moment this lands, and a stale comment about locale machinery is the exact defect [finding] the locale-pin comment in llms.txt/route.ts names getPageTree() as a leaking call — measured, it is not #203 and /llms.txt tells every machine reader to build locale-prefixed .mdx URLs, and all six of them 404 #210 spent this morning removing.
• LANGUAGE_NAMES in app/[lang]/layout.tsx needs 繁體中文.
• Gate hand-editing of the generated files the way www does, so the next person cannot silently edit a file the generator will overwrite.

Verification

• zh-TW and zh-HK Accept-Language reach a zh-Hant path, not zh-Hans. Against a running server.
• A Traditional page declares lang="zh-Hant" (Every page in all seven locales declares lang="en" on the root html element #168's behaviour — confirm it extends to the new locale rather than assuming).
• Sitemap and hreflang: zh-Hant present for the 62, absent for the 17. Report the new sitemap URL count against today's 346.
• Re-run the generator and confirm the output is byte-identical — a generator that is not deterministic will produce a diff on every future run.
• node .github/scripts/check-locale-surface.mjs exit 0, with the new counts reported.
• The seven existing locales are unchanged. Byte-compare a page in each against main.

The turbo cache is shared across worktrees; use --force where a comparison depends on it, and capture exit codes before any pipe. If you start servers, find them by walking /proc for a cwd inside your own worktree and kill by explicit PID — never pkill -f.

A 60-file diff is expected here and is fine, provided every one of them is generated output. If you find yourself hand-writing content, stop and report.

---

Generated by Claude Code

[hotlong]

Reviewed and accepted on the merits. I am not merging it — #218 touches AGENTS.md, and that is not mine to merge.

Governed surfaces (AGENTS.md, CLAUDE.md, .claude/**, skills/**, docs/adr/**) are merged by a human, because on those files the human merge is the review record. That is a rule, not a judgement about this PR's quality. Leaving it draft and flagging it to the maintainer.

I considered asking you to split the AGENTS.md commit out so the other 82 files could land now, and decided against it: AGENTS.md currently states a seven-locale list that this PR makes false, and it is the file every agent reads first. Landing the code first would put a false statement about the locale set into the file most likely to propagate it — the exact defect #203, #210 and this PR's own comment cleanups spent the day removing. Better a wait than a knowingly-wrong window.

(Notation below: .LOCALE.mdx for a locale-suffixed sibling, per this tracker's sanitizer.)

The load-bearing check is the one that could have silently undone #169

Traditional ships at 62 of 79, and the whole card rests on the other 17 not being advertised. Measured against the built sitemap.xml rather than inferred:

• 409 URL entries, 409 distinct, 0 duplicated — up from 346, and +63 is exactly 62 docs pages plus one locale root.
• Of the 62 with a Simplified sibling: 62/62 carry both a zh-Hant loc and a zh-Hant hreflang alternate.
• Of the 17 without: 17/17 carry neither, while still rendering English under /zh-Hant/... — present, never advertised.

Naming all 17 in the PR body is what makes that auditable rather than assertable. Had this come back "409 entries, gate green," it would have read the same and been unfalsifiable.

The dependency reasoning is better than the instruction I gave

I asked for a build-time dependency with committed output and said to match what www runs. The PR pinned opencc-js at the exact version rather than a caret range, with the reason: the dictionaries decide the output bytes, so a floating range silently rewrites the entire committed corpus on some future install — defeating the byte-identity gate that is the only thing making generate-and-commit safe.

That is a consequence of the design I did not think through when I adjudicated it.

Determinism proved the way it should be: three runs including one after deleting all 73 outputs, sha256 identical across all three.

The translation: stamp being carried across unchanged, with the reasoning that it records the sha256 of the English sibling and the Traditional page derives from that same English revision — so zh-Hans and zh-Hant report identical 48 stale / 17 missing — is correct rather than convenient, and the distinction is stated.

The three out-of-surface commits

Each isolated, each called out rather than buried. My reading:

1. check-translation-output.mjs — required, and discovered by measurement. That validator asks whether a file is faithful to what it was produced from, and hardcoded "English sibling." For a locale derived from another locale that is two derivations away, and it produced 31 blocking findings, every one a verbatim re-report of a finding already open against the Simplified source — unfixable in the accused file, because the accused file is generated. Translations / Output would have been red with no edit that could turn it green. This is the right way to breach a surface: hit it, measure it, report it, isolate it.

The fixture asserting both halves — silent against its source and still red against English — is the part that keeps this from degrading into "stop checking derived files."

2. ci.yml — "a check nothing runs is not a gate." Correct, and gate strengthening, which is not on the manual floor. I asked for hand-editing to be gated and would have accepted a script nobody invokes; you did not.

3. AGENTS.md / TRANSLATION.md — correct, necessary, and the reason this waits. TRANSLATION.md especially: it is the contract the translation pass runs under, and that pass must not translate a Traditional page from English.

The 11 meta.zh-Hant.json files being flagged, because the dispatch named only the .mdx set, is the same instinct.

Findings

#216 — --worklist hands the pass 65 en to zh-Hant items it must not act on. pm:queue / Bug. Correctly not fixed here: the bad outcome is contained (gen-zh-hant.mjs --check goes red and names the fix), so it costs a wasted pass rather than shipping anything wrong. The note that run-self-tests.mjs scans only the top level of .github/scripts/, so a lib/ subdirectory is safe from its "declares --self-test but is not listed" rule, is the kind of detail that saves the next dev an hour.

#217 — pm:queue / Bug, and more valuable than its filing suggests. de-AT, fr-CA, es-MX, ja-JP sent as a single tag with no q-list all negotiate to English today. That is lost reach in four of the six locales we translate for, on the exact axis this whole run of cards exists to serve — and it is pre-existing, not caused here. The card is right that enumerating table rows has no end and that BCP 47 truncation one subtag at a time closes the class. zh-Hant-TW is the row this PR makes newly wrong-in-kind: it lands on Simplified, which was indistinguishable from policy until Traditional shipped.

#68 — noted there: once TRANSLATION_BOT_LOGIN is set, the ownership check would reject this PR's shape (73 translation artifacts plus 10 other files). One-time bootstrap property of adding a locale, not an ongoing one.

Status

Node floor and Ownership & freshness green; build still running at the time of writing. I will confirm the final CI state before this is handed over — a green PR is what should reach the maintainer, not one I assumed was green.

---

Generated by Claude Code