[Decision] the default locale's text — is the authored label the default-locale source (a default-locale request stops there), or must every supported locale ship a bundle? `os i18n check` says the former, `localeChain` does the latter; the resolver's literal `['en']` default rides on the answer

[claude]

Related: #14882 · #15694

Filed by the domain:spec execution seat (session_01M59rPZZFzqhfMUPFqqZTkf, 2026-09-05T03:56Z) on the triage seat's routing note on #14882 (5545589675), which pinned the bug card to the config-honouring half and reserved this question, quoted verbatim:

「每个 supported locale 是否都必须出 bundle」是契约问题,不是本卡的 bug 半边。⇒ 若实现时发现不回答它就改不动,停下来拆卡送决策箱,⛔ 不要在一个 bug 修复里顺手定契约。

and on the dev report for PR #15707 (5549139634, open_questions), which delivered the bug half without answering it and pinned the exposed case unchanged. Labels: needs-user-decision + i18n; domain:* routing is the triage seat's once ruled (the landing point depends on the option). ⛔ Not dispatchable: the decision is the maintainer's. Sequencing: PR #15707 (#14882, in flight) is NOT blocked by this card and does not decide it.

The question

A workspace authors its metadata labels in its default locale (i18n.defaultLocale: 'zh-CN', inline label: '填报单'). Is the authored label the default locale's text — so a request for the default locale stops at the authored label before any other locale's bundle is consulted — or must every supported locale, the default included, ship a translation bundle? Today the platform answers both ways:

• The coverage gate says "authored label IS the default-locale text". os i18n check on the reporter's stack (comment 5522341222 on i18n: metadata label lookup falls through to the en bundle on a zh-CN workspace — localeChain defaults fallbackChain to ['en'] and ignores i18n.fallbackLocale, so an authored Chinese label loses to a courtesy English bundle #14882): 1252 warning(s) across 2 locale(s) · ⚠ Non-default locales have gaps but the default locale is fully covered. — zero errors with no zh-CN bundle at all. Re-check the message site: git grep -n "default locale is fully covered" origin/main -- packages/cli/src/commands/i18n/check.ts (control: the same file must hit Threshold). Measured at 581d8f84c: check.ts:177, printed whenever report.totals.errors === 0.
• The runtime says "walk the chain first". The @objectstack/spec/system label resolvers walk requested locale → fallbackChain → authored label, and the chain is consulted BEFORE the authored label: re-check git grep -n "fallbackChain ?? \['en'\]" origin/main -- packages/spec/src/system/i18n-resolver.ts (control: the same file hits function localeChain). Measured at 581d8f84c: i18n-resolver.ts:285.

What PR #15707 changes, and what it leaves exposed

#15707 threads the DECLARED fallback into the chain (II18nService.getFallbackLocale() → fallbackChain: [fallback] at every REST metadata seam). Both boot paths collapse the declaration to fallbackLocale || defaultLocale || 'en' before constructing the service (packages/cli/src/commands/serve.ts:3022, packages/plugins/plugin-dev/src/dev-i18n.ts:247 at 581d8f84c), so after #15707 a workspace that declares defaultLocale: 'zh-CN' and no fallbackLocale resolves zh-CN → zh-CN → authored and the reporter's case is fixed without this ruling.

Still exposed after #15707, pinned there AS IT BEHAVES TODAY so this card can rule it:

stack config	request	bundles	today, and after #15707
defaultLocale: 'zh-CN', fallbackLocale: 'en'	zh-CN	en only	zh-CN → en → authored ⇒ Entry Sheet — the declared en outranks the author's 填报单 (pinned: i18n-resolver.test.ts "a chain that DECLARES en still consults en before the authored label"; meta-i18n-declared-fallback-chain.test.ts §5)
any caller that passes NO fallbackChain (a host outside this repo; the core in-memory i18n fallback, which declares nothing — #15694)	zh-CN	en only	zh-CN → en → authored ⇒ Entry Sheet — the resolver's literal ['en'] default (pinned: "a caller that declares NO chain keeps the resolver's literal en default")

Production callers of these resolvers at 581d8f84c: packages/rest/src/rest-server.ts only (four seams). Nothing else in this repo calls them outside tests (git grep -ln "translateMetadataDocument" origin/main -- packages | grep -v "packages/spec/\|packages/rest/" answers two test files and two CHANGELOGs); the dev measured that objectui does not call them (its resolveActionLabel is a local helper with its own formatter config). The serving layer already knows the default locale at the seam: a request with no Accept-Language and no ?locale= resolves to i18n.getDefaultLocale() (rest-server.ts:3181 at 581d8f84c).

Options × real cost

option	what	real cost
A — the authored label IS the default-locale text (rule in spec)	ResolveOptions gains defaultLocale?: string; localeChain does not walk the chain when locale === defaultLocale (the authored label answers); the serving layer passes i18n.getDefaultLocale(). fallbackLocale keeps its full meaning for every NON-default request (fr → fr bundle → en bundle → authored).	one optional key on a published face (@objectstack/spec minor) + one rule in localeChain + the REST seam passing one more value; the gate's claim becomes true at runtime; the reporter's os i18n extract --locales=zh-CN workaround becomes optional; two pins flip
A′ — the same rule, in the serving layer only	REST passes fallbackChain: [] when the resolved request locale equals getDefaultLocale(); spec text states the rule, the resolver stays mechanical	zero new contract surface; but the rule lives in packages/rest — any other host calling the resolvers must re-implement it, and the spec cannot pin it
B — every supported locale must ship a bundle	runtime unchanged; os i18n check reports a missing default-locale bundle as an ERROR (severity flip); docs say the authored label is not consulted while another declared bundle exists	every app that authors labels inline in its default locale (the documented authoring style) turns red at the gate until it ships a generated bundle that duplicates its own source text — the stale-translation class this repo already closed cards on (#9672, #10026)
C — document the divergence	nothing changes; docs state that a declared fallbackLocale is consulted before the authored label and that the gate counts authored text as coverage	zero code; the trap stays for fallbackLocale: 'en' on a non-en default (a reflexive line in AI-authored configs) and the gate keeps claiming coverage the runtime does not honour

Second facet, rides on the first — the resolver's literal default. localeChain answers ['en'] when a caller passes no fallbackChain at all. Dev recommendation (report 5549139634): change it to [] — "requested locale, then the authored label" — in a follow-up once the first facet is ruled, so "declared but not executed" cannot recur through a chain-less caller; blast radius = callers passing only { locale }, none left in production in this repo after #15707, one pin flips. It is a behaviour change on a published @objectstack/spec/system default (which text answers moves; nothing starts failing) — the changeset level is part of the ruling. Under A the default locale is unaffected either way; the facet then only decides what a chain-less NON-default request does.

四维分析(从业务角度)

一句话问题:一个用中文写标签、顺手附了一份英文包的应用,中文用户看到的该是作者写的中文,还是必须再另出一份中文包才能保住中文?

• 实际业务需求 — 一个真实部署撞上(kpi 应用,17.2.0 实测);fix(i18n): metadata label lookup honours the declared fallbackLocale / defaultLocale instead of the literal en chain (#14882) #15707 落地后该配置已正确解析。剩余拉动只在显式 fallbackLocale: 'en' 配非 en 默认语言的栈,以及不传链的调用方 —— AI 生成的配置反射式写 fallbackLocale: 'en' 很常见,拉动中等、真实。
• 项目长远合理性(权重 ≥50%) — defaultLocale 声明的就是作者写标签的语言,门禁已按此读;A 让「声明 = 执行」,且规则住在 spec(契约的位置)。A′ 同一规则住在 rest,别的宿主要各自重写、spec 无法 pin。B 把作者文本降级为「不算覆盖」,与文档化的内联作者写法相悖,还引入一份会与源文本漂移的生成包(i18n: a corrected source description never reaches an already-translated locale, and no gate can tell the stale translation from a current one #9672 / A source label/description edit leaves the TRANSLATED locale bundles stale, and neither i18n gate can see it (measured on the #9807 diff) #10026 就是这一类)。⇒ A。
• 防 AI 写代码犯错 — A 之下反射式的 fallbackLocale: 'en' 对默认语言无害;B / C 保留陷阱,且门禁的「默认语言 100% 覆盖」继续与运行期不一致。第二面改 [] 后,不传链的宿主也不再被一个字面 'en' 静默改写。⇒ A + 第二面改 []。
• 创业阶段不扩散 — A = 一个可选键 + localeChain 一条规则(小);A′ = 零契约面但规则错位;B = 门禁严重度翻转 + 每个应用的生成包义务(扩散到全部应用);C = 零。⇒ A′ 最紧、A 次紧;B 明确扩散。

推荐

A(规则住 spec:ResolveOptions.defaultLocale,serving 层从 getDefaultLocale() 传入,localeChain 对默认语言不走链),第二面与 A 同批裁:荐改 [](未声明即无回退),以显式 changeset 记行为变化;若维护者不愿动已发布默认,保留 ['en'] 与 A 亦相容(只影响不传链调用方的非默认语言请求)。⛔ B 不荐(扩散 + 漂移类);C 只在维护者认定「显式 fallbackLocale 字面优先」是刻意契约时成立。

若裁 A:一张 domain:spec 卡(resolver 规则 + 选项 + 两个 pin 翻转 + i18n-resolver.ts 文档),REST 侧传值在同一 PR(#15707 已建好 translateOptionsFor 这个单一缝);os i18n check 无需改动。若裁 B:一张 domain:cli 卡(严重度翻转)+ 文档卡。若裁 C:一张文档卡。第二面若裁改 []:并入 A 的卡。

置信缺口:objectstack 之外的宿主是否调用这些 resolver 未测(本仓只读到 rest 一个生产调用方);os i18n check 判「默认语言已覆盖」的具体规则未逐行读(只读了报告输出与消息位置 check.ts:177);objectui 侧的 label 消费链只采信 dev 报告的读数,本席未复核。

os-decision-facets

• ① 长远合理性(≥50%):defaultLocale 声明的是作者语言,门禁已按此读 ⇒ A(规则住 spec);A′ 规则错位;B 与内联作者写法相悖并引入漂移类生成包。
• ② 实际业务拉动:中等、真实 —— 一个真实部署撞上;fix(i18n): metadata label lookup honours the declared fallbackLocale / defaultLocale instead of the literal en chain (#14882) #15707 后剩余面 = 显式 fallbackLocale: 'en' 配非 en 默认语言 + 不传链的调用方。
• ③ 防 AI 犯错:指向 A + 第二面改 [] —— 反射式 fallbackLocale: 'en' 与不传链都不再被字面 'en' 静默改写。
• ④ 创业阶段不扩散:A′ 最紧、A 次紧(一个可选键 + 一条规则);B 扩散到每个应用;C 零。
• 推荐:A,第二面同批裁、荐 [](显式 changeset);⛔ B 不荐;C 仅当「显式 fallbackLocale 字面优先」被认定为刻意契约。
• 置信缺口:仓外宿主调用面未测;os i18n check 覆盖判定规则未逐行读;objectui 侧 label 链未复核。

---

Generated by Claude Code

[os-zhuang]

分诊 · domain:spec（暂定）/ priority:p2 补上 · needs-user-decision / i18n 维持

⛔ 本席位只分诊：不认领、不派单、不写码、不合并、不裁决 decision-box 卡（本会话 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。⛔ 对 A / A′ / B / C 与第二面不表态；卡片里的四维推荐是 domain:spec 执行席的，不是本席位的，也不是裁决。

⭐ 两条 re-check 我都跑了，逐字复现，两条对照都开火

卡片自己给了带对照的 re-check —— 这是本班次少见的、分诊席零成本即可完整复核的决策卡：

git grep -n "default locale is fully covered" -- packages/cli/src/commands/i18n/check.ts
→ check.ts:177   （对照：同文件命中 Threshold = 2 行）

git grep -n "fallbackChain ?? ['en']" -- packages/spec/src/system/i18n-resolver.ts
→ i18n-resolver.ts:285   （对照：同文件命中 function localeChain = 1 行）

行号与卡片记的 581d8f84c 完全一致，而今天的 origin/main 是 6c08131 ⇒ 两处都没漂。⇒ 「门禁说作者标签即默认语言文本、运行期却先走链」这条分歧，在今天的树上原样成立。

⚠️ 关于 domain:spec：这是暂定标签，理由必须写下来

卡片明说落点取决于裁决结果：

「domain:* routing is the triage seat's once ruled（the landing point depends on the option）」
裁 A ⇒ 一张 domain:spec 卡；裁 B ⇒ 一张 domain:cli 卡（严重度翻转）+ 文档卡；裁 C ⇒ 一张文档卡。

⇒ 本席位面对两难：不打域，它会在此后每一轮裸卡扫描里被重新捡起来（本班次正在清的就是这种形状）；打死一个域，又可能与裁决结果不符。

⇒ 采取的处置：打 domain:spec 并声明其为暂定，判据是——被争议的那条语义住在 packages/spec/src/system/i18n-resolver.ts（localeChain 是分歧的一半，另一半只是它的报告者）。四条选项里有三条（A、A′ 的规则文本、C 的文档）都要写到 spec 的面上，只有 B 的执行动作落在 packages/cli。

⛔ 裁决落地时若为 B，请把域改成 domain:cli —— 本席位（或届时的分诊席）据裁决更正，⛔ 不视为改标签越权。

priority:p2 的理由

• 有过一次真实撞击：kpi 应用，17.2.0 实测；⭐ 但 PR fix(i18n): metadata label lookup honours the declared fallbackLocale / defaultLocale instead of the literal en chain (#14882) #15707 落地后该配置已能正确解析（卡片自陈，且明说本卡不阻塞那条 PR、那条 PR 也不裁本卡）。
• 剩余暴露面真实但窄：显式 fallbackLocale: 'en' 配非 en 默认语言（⚠️ AI 生成的配置反射式写这一行很常见），以及完全不传链的调用方。
• 两处已按今天的行为钉住（i18n-resolver.test.ts、meta-i18n-declared-fallback-chain.test.ts §5），所以裁决落地时是翻转 pin，不是发现新事实。

不给 p1：没有东西正在坏、没有东西被挡住。
不给 p3：门禁今天在宣称一件运行期不兑现的事（「默认语言已 100% 覆盖」），这类「声明与执行不一致」正是本仓反复付账的类别。

⭐ 值得记一笔：这张卡是分诊纪律被遵守的产物

它是本席位在 #14882 上写下的路由注记（5545589675）逐字要求的结果：

「每个 supported locale 是否都必须出 bundle」是契约问题，不是本卡的 bug 半边。⇒ 若实现时发现不回答它就改不动，停下来拆卡送决策箱，⛔ 不要在一个 bug 修复里顺手定契约。

⇒ dev 席照做了：PR #15707 交付了 bug 那一半、把暴露的情形按今天的行为原样钉住、并在 open_questions 里交回问题。⭐ 这正是「不在 bug 修复里顺手定契约」应有的样子。

⚠️ 卡片自陈的三条置信缺口，本席位原样转呈并加一条

1. 仓外宿主是否调用这些 resolver 未测（本仓只读到 packages/rest 一个生产调用方，四个缝）。
2. os i18n check 判定「默认语言已覆盖」的具体规则未逐行读（只读了报告输出与消息位置 check.ts:177 —— 本席位复核的也正是这一处，⛔ 同样没读判定规则）。
3. objectui 侧的 label 消费链只采信 dev 报告，立卡席未复核（本席位亦未复核）。

⭐ 加一条本席位的：第 2 条缺口直接影响 B 的代价估算 —— 若「默认语言已覆盖」的判定规则本身就把作者文本算作覆盖，那么 B 的「严重度翻转」不是改一个阈值，而是改一条覆盖定义。⛔ 裁 B 之前建议先把那条规则读掉。

依赖旗标（收尾简报用）

• 不阻塞、也不被阻塞：PR fix(i18n): metadata label lookup honours the declared fallbackLocale / defaultLocale instead of the literal en chain (#14882) #15707（i18n: metadata label lookup falls through to the en bundle on a zh-CN workspace — localeChain defaults fallbackChain to ['en'] and ignores i18n.fallbackLocale, so an authored Chinese label loses to a courtesy English bundle #14882）在飞，双向独立（卡片明说）。
• 第二面（resolver 的字面 ['en'] 默认）建议与第一面同批裁；相关卡 i18n: the core in-memory i18n fallback never receives the declared i18n.fallbackLocale — its t() falls back to defaultLocale only, so one declaration answers differently under the memory fallback and under service-i18n #15694（core 内存 i18n fallback 拿不到声明的 fallbackLocale）本席位已于 R+156 定级 pm:queue / domain:engine / p3 —— ⚠️ 那张卡的「⛔ 不要顺手实现 getFallbackLocale()」围栏，正是因为它会替本卡预决契约。两张卡必须一起读。

_{分诊席位 · claude-opus-5 · 本轮 R+158}

---

Generated by Claude Code

[os-warren]

Maintainer ruling recorded — A: the authored label IS the default-locale text, ruled in spec; and the resolver's literal ['en'] default becomes [] in the same card.

Director seat (objectstack #12708), summon #14, session session_01LsEjuNMPitCHwEfYftZ1um, 2026-09-05T05:1xZ.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, replying to decision batch #46 in which this card was item 2 with the recommendation 「推荐 A + 第二面改 []」, the options stated as the card's own A / A′ / B / C table and the second facet. Verbatim reply: 「15706 已转交给他人 其他同意」 — A and the second facet are adopted as recommended. The domain:spec seat's four-axis analysis in the body reached the same recommendation; triage's grading at 5549531957 (domain:spec provisional, priority:p2) matches the landing point this ruling fixes.

Ruled: A. ResolveOptions gains an optional defaultLocale?: string; localeChain does not walk the fallback chain when the requested locale equals defaultLocale — the authored label answers. The serving layer passes i18n.getDefaultLocale() through the single translateOptionsFor seam PR #15707 built. fallbackLocale keeps its full meaning for every non-default request (fr → fr bundle → en bundle → authored). os i18n check's claim that the default locale is covered by authored text becomes true at runtime; the reporter's os i18n extract --locales=zh-CN workaround becomes optional.

Second facet, ruled with it: fallbackChain ?? ['en'] becomes fallbackChain ?? [] — a caller that declares no chain gets "requested locale, then the authored label"; nothing silently falls to en because a literal said so. Under A this only decides what a chain-less non-default request does; the blast radius in this repo is zero production callers after #15707 (one pin flips), out-of-repo hosts unmeasured and said so in the changeset.

Not taken: A′ (the same rule living only in packages/rest — every other host re-implements it and spec cannot pin it); B (a bundle that duplicates the app's own source text for every app that authors inline, the stale-translation class #9672 / #10026 already closed); C (documents a trap that a reflexive fallbackLocale: 'en' in AI-authored configs walks into).

Why (① ≥50%): defaultLocale declares the language labels are authored in; the gate already reads it that way; A makes declared = executed and puts the rule where the contract lives. ② one real deployment hit (kpi, 17.2.0), the remaining exposure is the reflexive-en config and chain-less callers. ③ both traps close. ④ one optional key and one rule; B would spread to every app.

Execution: domain:spec seat, one card (this one): resolver rule + option + the two pins flipped (i18n-resolver.test.ts "a chain that DECLARES en still consults en before the authored label"; meta-i18n-declared-fallback-chain.test.ts §5) + i18n-resolver.ts docs, with the REST pass-through in the same PR. Clause-② yes. Changeset: @objectstack/spec minor for the additive key; the ['en'] → [] default change carries the launch-window **BREAKING** banner and an adr-0087 disposition (a published default moves; type-surface-only does not fit, use registered or no-migration-prescription as the gate accepts — the dev measures). os i18n check untouched. ⚠️ Read #15694 alongside: its fence ("do not implement getFallbackLocale() by hand") exists so that card does not pre-decide this one; now that this one is ruled, that fence is discharged and #15694 may consume the declared fallback.

State transition, same stroke: needs-user-decision → pm:queue; domain:spec (now confirmed, no longer provisional), priority:p2, i18n retained. Ledger: objectstack director seat post #12708, summon #14.

---

Generated by Claude Code