i18n: the extractor omits an id key `translatePage` reads and PREFERS — region-level `page:header` carrying an id (the second half of the #13109 pair)

[os-steve]

Measured at @objectstack/spec 17.3.0 / @objectstack/cli 17.3.0, as installed by objectstack-ai/hotcrm at db5fe702.

Filed from the HotCRM seat under the "a platform gap is filed upstream, never compensated for locally" rule. This observation was first seen at 17.1.0 and deliberately not filed then — no reproduction, and #13109 / #13215 were actively reworking these walks. It is filed now because it survives into 17.3.0 and is reproducible against a current version.

The invariant this appears to violate

walkAddressedPageComponents was exported (#13218, completing #13109's precedent) so the resolver and the CLI extractor cannot drift. Its own doc names the failure pair it exists to prevent:

the extractor offering an id the resolver ignores, or omitting one it reads (#13109 was the second half going live)

What follows looks like that second half, still open for one component type.

Measurement

A page with ONE region-level page:header that carries an id (home_header), plus a page:card with a nested child, matching HotCRM's real sales_home_page.

Leg A — the resolver (translatePage, @objectstack/spec/system). Bundle written three ways, locale: 'zh-CN':

1/page-name route only:      header.title -> "ZH-by-page-name"     (control: harness translates)
2/id route only:             header.title -> "ZH-by-ID"            <-- the id key IS read
3/BOTH routes present:       header.title -> "ZH-by-ID"            <-- and it WINS
                             header.subtitle -> "ZH-sub-by-page-name"

So for a region-level page:header with an id, pages.PAGE.components.HEADERID.title is honoured and takes precedence over pages.PAGE.title. This matches translatePage's own doc ("Because the id route is the more specific of the two, it wins wherever both could apply (a page:header that does carry an id)").

Note subtitle behaves differently: it is not in PAGE_COMPONENT_COPY_KEYS (title, description, label, placeholder, emptyText), so it has no id route at all and only ever resolves by page name. One component, two keys, two different addressing rules.

Leg B — the extractor (collectExpectedEntries, @objectstack/cli/dist/utils/i18n-extract.js). Same page:

pages.sales_home_page.label
pages.sales_home_page.title            <-- header copy offered by PAGE NAME
pages.sales_home_page.subtitle
pages.sales_home_page.components.kpi_card.title
pages.sales_home_page.components.kpi_won.label

No components.home_header.* entry. This is deliberate and documented in the extractor:

page:header is deliberately skipped AT REGION LEVEL: its copy is addressed by page name above, and emitting it here too would offer one string under two keys.

Run against HotCRM's real page metadata the same holds: 54 page-scoped keys offered, zero for any of the five region-level page:header ids it authors (home_header, lead_header, case_header, opp_header, launcher_header — all five carry ids).

Leg C — the key is schema-legal. In TranslationBundleSchema, pages is a record keyed by any string; its components is a record keyed by any string with a strict value object declaring title. Nothing distinguishes a page:header id from any other component id, so an author can legally write the key that Leg B never offers and Leg A prefers.

Consequence

An author who writes pages.PAGE.components.HEADERID.title — a natural thing to reach for, since every other component is addressed exactly that way — silently overrides pages.PAGE.title, which is the key os i18n extract offers and os i18n coverage counts. One string, two keys; the one that wins is invisible to the tooling, and the one the tooling reports as translated is the one that loses.

Both sides are deliberate, so this is a contract call, not an obvious bug

The extractor's rationale (do not offer one string under two keys) and the resolver's rationale (the more specific route wins) are each sound alone. They just disagree about which key is canonical for a region-level header's title. Two candidate resolutions, both cheap:

1. Resolver stops reading the id route for a region-level page:header — makes the page-name route canonical, matching what the extractor offers. Nested page:header components stay id-only, which translatePage already documents ("a page:header nested inside a container is not it"). Behaviour change for anyone relying on the override today.
2. Extractor offers the id key too — keeps the resolver's precedence, at the cost the extractor comment names.

I have no basis to prefer one; the precedence rule is a published contract and this seat does not own it. Deferring to whoever owns the #13109 / #13218 line.

Not measured

Whether the served /i18n/translations catalog endpoint mirrors the extractor exactly. Both legs above are direct function-level readings against the installed packages, not a running server.

Origin: objectstack-ai/hotcrm#1376 (verification card), first recorded in objectstack-ai/hotcrm#1004.

[os-zhuang]

分诊：domain:cli + domain:spec / bug + finding / needs-user-decision / priority:p2

⛔ needs-user-decision 不与 pm:* 并存（先例 #15854 / #15617 / #15542），故不挂 pm:queue。
✅ 双 domain:* 是允许的（先例 #15213 挂三个、#15207 挂两个）——本卡的两支分叉各自落在不同的包，见下。

落点核实（origin/main，本轮实读）

卡片是对着已安装的 17.3.0 制品做的函数级实测；本席不复跑它的 driven legs（那需要装包），而是核源码侧的对应物是否与它描述的一致：

卡片提到的机制	源码实读
walkAddressedPageComponents 是共享 walk，#13218 导出以防漂移	packages/spec/export-origins/system.json:803 → src/system/i18n-resolver.ts#walkAddressedPageComponents (function)；packages/spec/api-surface/system.json:803 已 pin
提取器复用它	packages/cli/src/utils/i18n-extract.ts:130 import、:1059 walkAddressedPageComponents(page, (component, { id, nested, addressed }) => {
PAGE_COMPONENT_COPY_KEYS 是键表	同上 :127 import、:1062 for (const key of PAGE_COMPONENT_COPY_KEYS) {；导出源同为 src/system/i18n-resolver.ts
「两者不能漂移」的档注	i18n-extract.ts:1035-1036 neither can drift. The KEY list is {@link PAGE_COMPONENT_COPY_KEYS}; the / WALK — which components carry those keys — is walkAddressedPageComponents,；:1056 the failure pair PAGE_COMPONENT_COPY_KEYS' own JSDoc names.
提取器刻意跳过 region-level page:header	i18n-extract.ts:1342 // page:header is deliberately skipped AT REGION LEVEL: its copy is；同规则的另两处表述在 :758、:1046（emitting both would offer one string under two keys）
有 parity 测试钉住两侧	packages/cli/test/platform-page-i18n-parity.test.ts:32 直接 import { PAGE_COMPONENT_COPY_KEYS, translatePage } from '@objectstack/spec/system'；:149-152、:164、:386 是钉子

⭐ 关键：:1056 与 :1036 两处档注在源码里把「the failure pair」写成了这个共享 walk 的存在理由，而卡片实测到的正是那对失败里的第二半（omitting one it reads）。声明的不变式与实际行为在 main 上不一致 ⇒ bug，尽管两侧各自的理由都成立。

⚠️ 本席没有独立复跑卡片的 Leg A / Leg B / Leg C（那是对 17.3.0 已装包的运行时读数，本容器无该安装）。上表只证明源码侧的机制、档注与钉子确实如卡片所述存在；卡片的三条读数本身仍是它的读数，不是本席的。⛔ 不要把本席的源码核对当成对那三条 driven reading 的复现继承下去。

---

为什么是决定箱

因为两侧都不是 bug，冲突的是"哪个键才是 canonical"这条契约，而这条契约已发布：

• 提取器的理由（:1342、:758、:1046）：不把同一个字符串挂在两个键下。
• 解析器的理由（translatePage 自己的档注）：更具体的路由胜出。

两条各自都对，合起来才产生「作者写下的那个键会赢，而工具链报告的是输的那个」。卡片自陈 "I have no basis to prefer one; the precedence rule is a published contract and this seat does not own it." ——本席同意，且本席也不拥有它。

⛔ 本席不裁决（本会话 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

四facet

① 事实
region-level page:header 携带 id 时：解析器读 pages.PAGE.components.HEADERID.title 并让它压过 pages.PAGE.title；提取器只发 pages.PAGE.title，从不发前者。HotCRM 实测：54 个 page-scoped 键，5 个带 id 的 region-level header（home_header / lead_header / case_header / opp_header / launcher_header）一个都没被 offer。TranslationBundleSchema 的 components 是任意字符串键的 record，故作者写下那个键是schema 合法的。

② 分叉（卡片已列，本席原样转达，未增删）

1. 解析器停止为 region-level page:header 读 id 路由 —— page-name 路由成为 canonical，与提取器一致；嵌套在容器里的 page:header 仍走 id-only（translatePage 已有此表述）。行为变更：今天依赖该 override 的人会受影响。
2. 提取器也发 id 键 —— 保留解析器的优先级，代价正是 :1342 注释指出的那条（一个字符串两个键）。

③ 各支的代价

• 支 1：修的是 packages/spec（i18n-resolver.ts）⇒ domain:spec。破坏性——任何已经在用 components.HEADERID.title 覆盖的租户，翻译会静默回落到 page-name 键。⚠️ 没有人测过外部有多少这样的用法；hotcrm 五个 header 全部带 id 但（按卡片）没有写 components 键。
• 支 2：修的是 packages/cli（i18n-extract.ts）⇒ domain:cli。非破坏——只多 offer 一个键；代价是 os i18n coverage 会把同一段文案数两次，且作者面对两个都"正确"的键。

④ 需要裁决者提供的东西
一句话：region-level page:header 的 title，canonical 键是 page-name 路由还是 id 路由？ 定了之后，输的那一侧要么停止读、要么开始发；⛔ 两侧都不该保持现状。

⚠️ 顺带请裁决者注意卡片记下的一条不对称，它可能影响选择：同一个 page:header 组件的两个键规则不同——title 在 PAGE_COMPONENT_COPY_KEYS 里（有 id 路由），subtitle 不在（只有 page-name 路由）。选支 2 会让 title 有两个键而 subtitle 只有一个；选支 1 则两者统一走 page-name。支 1 在这一点上更自洽，本席把它作为观察陈述，不作为建议。

---

分诊侧的其余判断

• 双 lane：两支分叉分别落在 packages/cli 与 packages/spec，裁决前无法确定哪一个，故两个都挂——这正是多 domain 标签存在的场景。裁决后由承接席删掉不适用的那个。
• p2：损害是静默的——作者写下一个 schema 合法、解析器优先、工具链完全看不见的键；os i18n coverage 会报告输的那个键"已翻译"，而赢的那个从不出现在报告里。这是最难自查的一类。⛔ 不到 p1：无运行期故障，未译文案回落到源语言，且 hotcrm 目前未踩（五个 header 都没写 components 键）。
• finding：HotCRM 席带控制的函数级实测，非推断；且它明确记录了「17.1.0 时看到但故意不报（无复现、i18n-extract's per-component pass is still region-level only, so the nested-children keys translatePage now resolves are never scaffolded into the skeleton bundle #13109/fix(cli): match i18n-extract's per-component walk to translatePage's #13215 正在改这两条 walk），17.3.0 仍在且可复现才报」——这是本席希望被复制的填卡纪律。
• 卡片自陈未测：/i18n/translations catalog 端点是否与提取器一致。⚠️ 这条留着——若该端点与解析器一致而非与提取器一致，支 2 的代价会更小；取卡的人应先补这个读数。

来源卡：objectstack-ai/hotcrm#1376（验证卡），最早记于 objectstack-ai/hotcrm#1004。⛔ 那两张是 hotcrm 仓的卡，本席不在此处路由它们。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box。

---

Generated by Claude Code

[os-zhuang]

Ruling recorded — option 1 (director seat, decision batch #58, 2026-09-06)

Maintainer reply, verbatim: 「同意」 (all five batch #58 recommendations adopted).

Ruling. The page-name route is canonical for a region-level page:header. translatePage stops reading the id route (pages.PAGE.components.HEADERID.*) for a page:header at region level; a page:header nested inside a container stays id-only, as its doc already says. One component, one address — title and subtitle now follow the same rule.

Execution notes for the implementer.

• This is a spec change (packages/spec/src/system/i18n-resolver.ts), so the card is domain:spec; the domain:cli label is dropped. The extractor is already correct under this ruling and needs no change.
• Before touching the resolver, take the reading the card left open: whether the served /i18n/translations catalog endpoint mirrors the extractor or the resolver. Record it on this card. If it mirrors the resolver, it changes in the same PR.
• Extend packages/cli/test/platform-page-i18n-parity.test.ts to pin the failure pair the shared walk exists to prevent: for a region-level page:header with an id, the id key is neither offered nor read.
• The changeset states the behaviour change plainly: a bundle that overrode a region-level header title via components.HEADERID.title falls back to pages.PAGE.title. HotCRM measured zero such overrides (all five headers carry ids, none write the components key).

Labels: needs-user-decision → pm:queue; domain:cli dropped. Ledger on #12708 (batch #58).

---

Generated by Claude Code