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

[baozhoutao]

Summary

For an app whose metadata labels are authored in the workspace default locale (zh-CN, inline label: '填报单') and which ships only an en translation bundle as a courtesy for English users, the metadata API serves the English bundle labels to a zh-CN request. The authored Chinese label never wins because the label lookup's fallback chain is hard-wired to ['en'], independent of the stack's i18n.fallbackLocale.

The effect on screen: object title Entry Sheet, columns Sheet / Plan / Subject / Status / Final Score, app name KPI Assessment — sitting next to fields that have no en entry and therefore correctly show 主体类型 / 填报说明, and next to platform chrome that is fully Chinese. A zh-CN deployment cannot ship an en bundle without breaking its own default language.

Minimal reproduction

Platform 17.2.0, objectstack dev, SQLite, single tenancy, fresh DB.

objectstack.config.ts:

i18n: { defaultLocale: 'zh-CN', supportedLocales: ['zh-CN', 'en'], fallbackLocale: 'zh-CN' },
translations: [defineTranslationBundle({
  en: { objects: { kpi_entry_sheet: { label: 'Entry Sheet', pluralLabel: 'Entry Sheets',
        fields: { name: { label: 'Sheet' }, status: { label: 'Status' }, total_score: { label: 'Final Score' } } } } },
})],

kpi_entry_sheet object: label: '填报单', fields name: Field.text({ label: '填报单名称' }), status: Field.select({ label: '状态' }), total_score: Field.number({ label: '最终得分' }), subject_type: Field.select({ label: '主体类型' }) (no en entry for subject_type).

GET /api/v1/i18n/locales
→ {"locales":[{"code":"zh-CN","isDefault":true},{"code":"en","isDefault":false}]}

GET /api/v1/meta/object/kpi_entry_sheet   (Accept-Language: zh-CN, signed in as admin)
→ item.label        = "Entry Sheet"     ← expected 填报单
  item.pluralLabel  = "Entry Sheets"
  fields.name       = "Sheet"           ← expected 填报单名称
  fields.status     = "Status"          ← expected 状态
  fields.total_score= "Final Score"     ← expected 最终得分
  fields.subject_type = "主体类型"       (no en entry → authored label survives)
  fields.created_at = "创建时间"         (platform zh-CN pack → correct)

GET /api/v1/meta/object/kpi_entry_sheet   (Accept-Language: en)
→ identical for the app fields; created_at = "Created At"

GET /api/v1/meta/app/kpi_app               (Accept-Language: zh-CN)
→ label = "KPI Assessment"                ← authored label is 'KPI 考核管理'

Same request with no Accept-Language header: same English result (the workspace default is zh-CN).

Control: remove the en bundle → every label is Chinese. So the presence of a bundle for a non-requested locale changes what the requested locale sees.

Where

@objectstack/spec system — the label resolvers (lookupObjectField, lookupObjectFieldAttr, lookupAppAttr, resolveViewLabel, lookupTabLabel, …) all iterate localeChain(opts):

function localeChain(opts) {
  const locale = opts?.locale ?? "en";
  const fallbacks = opts?.fallbackChain ?? ["en"];   // ← hard-wired
  ...
  for (const code of [locale, ...fallbacks]) ...
}

and return the first bundle hit before the caller falls back to the authored label. The server-side caller does not pass a fallbackChain, so i18n.fallbackLocale: 'zh-CN' has no effect on the chain: zh-CN → en → authored. For any object the zh-CN bundle does not mention (i.e. every object whose labels are authored in Chinese), the en bundle is consulted before the authored label.

Expected

One of (in order of preference):

1. The chain honours the stack's i18n.fallbackLocale / defaultLocale instead of a literal ['en'], so a zh-CN workspace resolves zh-CN → (fallbackLocale) → authored label, and en is only consulted when en is requested.
2. When the requested locale is the workspace default locale, the authored label wins over any other locale's bundle (the authored label is the default-locale text — that is what defaultLocale declares).
3. Failing both, the metadata API should at least not report locale: zh-CN while serving en strings; the i18n coverage tooling should flag "label served from a locale other than the requested/default one".

Side effects seen in the app (for triage, same root cause)

• Related lists show what looks like a duplicate column pair 指标 / Indicator: indicator (lookup, no en entry → authored 指标) next to indicator_name (has en entry → Indicator). With the fix both read Chinese (指标 / 指标名称).
• Record page title suffix (客户满意度 Indicator), breadcrumb (Indicator, Assessment Plan), related-list section headings (Entry Line 0, Indicator 0) all flip to English on a zh-CN page.

Environment

@objectstack/* 17.2.0 (runtime, spec, cli, console 17.2.0) · Node 22 · better-sqlite3 · single tenancy · objectstack dev. App: objectstack-ai/kpi (private) — the config above is a faithful excerpt.

[baozhoutao]

Additional data point — the platform's own coverage gate and the runtime disagree about what "default locale" means:

$ os i18n check
  1252 warning(s) across 2 locale(s)
  ⚠ Non-default locales have gaps but the default locale is fully covered.

os i18n check treats the authored (Chinese) labels as full coverage of the default locale zh-CN — no zh-CN bundle is required, zero errors. The runtime label lookup does not: with no zh-CN bundle entry it walks localeChain to en and serves the English bundle to a zh-CN request. So an app that passes the coverage gate 100 % for its default locale still renders that locale in English wherever a secondary-locale bundle exists.

Whichever way this is ruled, the two should agree:

• if authored labels are the default-locale source (what i18n check assumes), the lookup must stop at the authored label for the default locale instead of trying other bundles first;
• if every supported locale must ship a bundle (the os i18n extract per-locale workflow), then i18n check should report the missing default-locale bundle as the error it already claims to treat as one, and the docs should say the authored label is not consulted when any other bundle exists.

App-side we can work around it by generating the zh-CN bundle from schema labels (os i18n extract --locales=zh-CN), which is the documented per-locale layout — noting it here so the ruling can say whether that is the intended contract or a workaround.

[os-zhuang]

分诊路由(本评论来自分诊座位)· R+150 — domain:spec · pm:queue · 保留 bug + i18n + priority:p2。

落点实测(origin/main,fetch 后 git grep):

packages/spec/src/system/i18n-resolver.ts:283   function localeChain(opts?: ResolveOptions): string[] {
packages/spec/src/system/i18n-resolver.ts:285     const fallbacks = opts?.fallbackChain ?? ['en'];

⇒ 报告里逐字引的那两行就在 packages/spec,['en'] 硬编码今天仍在树上 ⇒ 前提成立,落点 domain:spec(单一属主车道)。

bug 而非 feature,判据要紧:栈声明了 i18n.fallbackLocale,而解析链不读它 ⇒ 这是「声明 ≠ 执行」,按机械边界判据属 Bug/整理侧,⛔ 不上人工地板。⚠️ 但派发时必须把范围钉在这一半:让链尊重已声明的 fallbackLocale / defaultLocale。

⭐ 卡上 2026-09-03T07:43Z 那条补充评论(5522341222)里藏着一个不同性质的问题,⛔ 别顺手一起裁掉:os i18n check 报「默认语言覆盖完整」(把作者写的标签当作默认语言的来源),而运行期解析不这么认为 —— 门禁与运行期对「默认语言」的定义不一致。「每个 supported locale 是否都必须出 bundle」是契约问题,不是本卡的 bug 半边。⇒ 若实现时发现不回答它就改不动,停下来拆卡送决策箱,⛔ 不要在一个 bug 修复里顺手定契约。

p2 维持(⛔ 本席未提级,理由写下):这条确实是用户可见、可复现、影响一个 zh-CN 部署的默认语言(17.2.0 实测),但 ① 无数据损坏、② 只在部署额外发了第二个 locale bundle 时才发作、③ 报告人自己已给出可用规避(os i18n extract --locales=zh-CN 生成 zh-CN bundle,且那是文档化的 per-locale 布局)。⇒ 不到 p1。⚠️ 若该规避被裁为不是预期契约,严重度应重估。

---

Generated by Claude Code

[os-project-manager]

Claim: PM loop round R1
Session: session_01M59rPZZFzqhfMUPFqqZTkf
Branch: claude/issue-14882-i18n-fallback-chain-honours-config
Worktree: objectstack-issue-14882
Domain: domain:spec
File surface: packages/spec/src/system/i18n-resolver.ts (localeChain at :283–:285 on 1be26b0, ResolveOptions.fallbackChain at :199, the lookup-order docblock at :34) + its tests · the server-side producer of the ResolveOptions passed to the label resolvers (to be located by the dev on origin/main — nothing outside packages/spec passes fallbackChain today, measured 01:48Z; the caller is where i18n.fallbackLocale / defaultLocale must be threaded from, and if it lives in packages/rest / plugin-hono-server / packages/metadata the dev reports the location and fixes on the producer side, not with a consumer-side patch) · generated followers · changeset. Stop on breach; explain in the report.
Container & model: M, mode:subagent, model: fable (claude-fable-5-1) — node scripts/pm/dispatch-gates.mjs --tier packages/spec/src/system/i18n-resolver.ts run 2026-09-05T01:48Z against the tree at 1be26b0: "no path-derived mandate", "Clause ② SUSPECT surface" hint; tier set from card CONTENT — the default resolution behaviour of a published @objectstack/spec/system resolver changes (which bundle wins for a default-locale request), and the claim-time rule is "not sure ⇒ yes" ⇒ CONTRACT_REVIEW_TIER (claude-fable-5-1, re-derived from origin/main:scripts/pm/dispatch-gates.mjs at 01:44Z).
Clause-②: yes
Serial constraints cleared: packages/spec/src/system/i18n-resolver.ts has no in-flight claim and is not on this seat's hot-file queue at 01:49Z; system/tenant.zod.ts and the generated i18n bundles are HELD by draft PR #15626 (#14478) — this card does not touch them, and if the dev's diff regenerates an i18n bundle it stops and reports before enqueuing; queued sibling #14972 (injected system-column labels, objectql/spec) is not in flight and is ⛔ not folded here (different defect, different fix). Same-round dispatches #14079 and #14954 are source-disjoint; generated corpus lands serially via scripts/pm/os-regen-merge.sh. Predecessor's linger PRs #15438 / #15639 / #15645 / #15626 touch none of this surface.

---

Generated by Claude Code