component.zod.ts 的 I18nLabelSchema 键声明为纯字符串,但 3 个平台页在 31 处授权内联多语言 map

[os-zhuang]

实施 #5611(RecordDetailsProps.sections 改对象形式)时,按"规则消费半径"清扫 component.zod.ts 的真实授权方发现的范围外问题 —— 与 #5611/#5176 同一族(声明与授权不一致,靠 props 无解析闸门苟活),但不是同一个键,故另开。未在 #5611 的 PR 中修复。

实测

packages/spec/src/ui/i18n.zod.ts:80 把 I18nLabelSchema 定义为纯字符串,且文档注释明确排除内联 i18n 对象:

export const I18nLabelSchema = lazySchema(() => z.string().describe('Display label (plain string; i18n keys are auto-generated by the framework)'));

"Developers only need to provide the default-language string; translations are managed through translation files, not inline i18n objects."

而 component.zod.ts 用它声明的键,被平台页大量授权为内联多语言 map:

• RecordRelatedListProps.title(component.zod.ts:189)→ I18nLabelSchema.optional()
• PageTabsProps.items[].label(component.zod.ts:118)→ I18nLabelSchema(必填)
• PageAccordionProps 同形(component.zod.ts:297)

真实授权(共 31 处,分布在 3 个已发布平台页):

// packages/platform-objects/src/pages/sys-organization.page.ts:55
label: { en: 'Members', 'zh-CN': '成员', 'ja-JP': 'メンバー', 'es-ES': 'Miembros' },
// packages/platform-objects/src/pages/sys-position.page.ts:66
title: { en: 'Holders', 'zh-CN': '任职人员', 'ja-JP': '在任者', 'es-ES': 'Titulares' },

文件	内联 map 授权处数
sys-user.page.ts	19
sys-organization.page.ts	6
sys-position.page.ts	6

这一形状是被兑现的,不是死代码。 objectui 的 record-details.tsx:194 用 pickLocalized(rawTitleSrc, language) 真的解析它;仓内 packages/cli/src/utils/i18n-extract.ts:398-401 也明确知道并处理这一形状(注释:"a localized-map label ({ en, 'zh-CN' }) is already multilingual")。所以这与 #4667 退休的 book 内联 translations 不同 —— 那个没有任何 resolver 读取,这个有。

为什么现在值得处理

• 今天已有的损害:声明即文档。 生成的 content/docs/references/ui/component.mdx 会照 schema 告诉作者 title / label 是 string。一个照参考写的 AI 作者会授权纯字符串,得到一个只有单语言的平台页;而仓库自己的平台页全部反过来写。权威文档是错的那一份 —— 与 RecordDetailsProps 与真实页面的授权形状不符:sections 声明为 string[] 但所有页面授权对象形式,hideFields 完全未声明 #5611 完全同一条理由。
• SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068 闸门落地时会硬失败。 z.string() 会直接拒绝 {en, zh-CN, ...} 对象,3 个已发布平台页的 31 处授权全部变成硬解析错误。

需要裁定的方向

不自行猜测,列出选项:

• A:收紧页面 —— 平台页改为纯字符串 + 走 translation bundle(objects.*._sections.*.label 等)。与 I18nLabelSchema 现有文档一致、与 清空剩余 6 条 authorWarn 死键 —— book ×2 / job.id / translation.validationMessages / app.homePageId / app.areas[].order（ADR-0049，v17 限时） #4667 方向一致;代价:31 处改写,且要确认每个键都有 bundle 归宿(tab label / related-list title 是否有 resolver 需先测)。
• B:放宽 I18nLabelSchema —— 改为 z.union([z.string(), z.record(z.string(), z.string())])。一处改动即覆盖全部键;代价:把内联 map 固化成长期契约,与该 schema 现有文档和 清空剩余 6 条 authorWarn 死键 —— book ×2 / job.id / translation.validationMessages / app.homePageId / app.areas[].order（ADR-0049，v17 限时） #4667 的退休方向相反。
• C:只放宽被兑现的那几个键 —— 最差:同一文件内 label 契约分叉。

倾向 A,但需先测 tab label / related-list title 在 bundle 侧有无 resolver(#5377 提示 view 的 tabs[].label 正是"无 translation key 也无 resolver"),若无则 A 会造成翻译能力倒退。这超出 #5611 的范围与我的判断范围,故不动、只记录。

关系

• 与 RecordDetailsProps 与真实页面的授权形状不符:sections 声明为 string[] 但所有页面授权对象形式,hideFields 完全未声明 #5611 / RecordHighlightsField does not declare readonly, so the spec silently strips the key the chip gate reads #5176 同族但不同键;RecordDetailsProps 与真实页面的授权形状不符:sections 声明为 string[] 但所有页面授权对象形式,hideFields 完全未声明 #5611 的 PR 已合规地未越界(它只声明 sections[].label 为 I18nLabelSchema,与本文件其余键保持一致,不为单个键分叉契约 —— 正因如此,这两处 section label 也落入本 issue 的范围)。
• 与 SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068 的关系同 RecordDetailsProps 与真实页面的授权形状不符:sections 声明为 string[] 但所有页面授权对象形式,hideFields 完全未声明 #5611:必须在 props 校验闸门 warning→error 升级前解决,否则闸门一升级即产生硬解析错误。建议按 RecordDetailsProps 与真实页面的授权形状不符:sections 声明为 string[] 但所有页面授权对象形式,hideFields 完全未声明 #5611/RecordHighlightsField does not declare readonly, so the spec silently strips the key the chip gate reads #5176 先例登记为 SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068 的前置。
• 参考 spec: view tab labels (tabs[].label) have no translation key and no resolver — the list-page tab bar is untranslatable in every locale #5377(view 的 tabs[].label 无 translation key 无 resolver)—— 不同表面,但同一"标题翻译能力"族,A 方案的可行性取决于它。

[os-zhuang]

追加一处同形状、但本 issue 键表未覆盖的:element:text.content(8 处)

在 #5068 的 props 闸门落地后,对 example 语料 + 平台页跑了一遍完整清单。本 issue 记录的 31 处内联多语言授权在闸门里表现为 34 条 component-props-invalid(计数口径不同:本 issue 按源码授权处数,闸门按每次 parse 的 issue 数,一个 page:tabs 的 9 个 tab label 报 9 条):

键	声明	闸门报出
PageTabsProps.items[].label	I18nLabelSchema(必填)	14
RecordRelatedListProps.title	I18nLabelSchema.optional()	13
RecordRelatedListProps.add.label	I18nLabelSchema.optional()	5
RecordDetailsProps.sections[].label	I18nLabelSchema.optional()(#5611)	2

另有 8 条落在本 issue 键表之外,值得并进同一次裁定:

packages/platform-objects/src/pages/sys-user.page.ts 的 8 个 element:text 节点把 properties.content 授权为内联多语言 map,而 ElementTextPropsSchema.content 声明的是裸 z.string() —— 不是 I18nLabelSchema。

component-props-invalid  content: Invalid input: expected string, received object   (8 sites)
  slots.tabs.properties.items[7].children[0].properties.content
  slots.tabs.properties.items[7].children[1].properties.content
  …

这一条对三个方向的影响不一样,所以不能默认「跟着 label 走」:

• A(收紧页面):content 是正文而不是标签,objects.*._sections.*.label 那套 bundle 归宿对它不适用 —— 需要单独回答「SDUI 正文文案的翻译通道是什么」,不然 A 对这 8 处就是能力倒退而不是收紧。
• B(放宽 I18nLabelSchema):覆盖不到这 8 处 —— content 根本不是用 I18nLabelSchema 声明的。选 B 的话必须显式决定 content 怎么办,否则闸门升 error 时这 8 处仍然是硬解析错误。
• C(只放宽被兑现的键):本 issue 已判为最差,不变。

即:无论选哪个方向,element:text.content 都需要在同一次裁定里被点名。故记在这里而不是另开 issue(#4949 的「attach, don't scatter」)。

同族但不同键、已另开的两处:#5775(renderer 兑现但未声明 / 声明了没人读)、#5777(InlineActionSchema.params 的两种形状)。

---

Generated by Claude Code

[os-zhuang]

存量裁决轮（维护者 2026-08-06 委托，session_01LeEfA7CFwbJb7JJmXm2KM3）：转决策箱（needs-user-decision）。这是真正的契约方向拍板：I18nLabelSchema 纯字符串声明（i18n.zod.ts:80 经 origin/main 核实）与 3 个平台页 31+ 处被 resolver 真实兑现的内联多语言 map 冲突——A（收紧页面走 bundle）/ B（放宽 schema）/ C 的取舍取决于翻译通道路线，且 08-06 评论补充的 element:text.content 8 处在任何方向下都须同批点名。本单是 #5068 闸门 error 升级的硬前置，与 #5775/#5777 宜同场拍板。

---

Generated by Claude Code

[os-zhuang]

维护者裁定（2026-08-06，经 PM 会话 session_01LeEfA7CFwbJb7JJmXm2KM3 誊写）：方向 B —— 放宽 schema。

• I18nLabelSchema 改为 z.union([z.string(), z.record(z.string(), z.string())])（保持 lazySchema 形态），文档注释同步改写：默认语言字符串或内联 locale map 均为授权形状；translation-bundle 通道保留为长期方向，待未来 i18n 项目立项时另议——不作为本单范围。
• 同批必做：element:text.content（8 处，本单 08-06 评论）改用同一放宽后的 schema（ElementTextPropsSchema.content：裸 z.string() → I18nLabelSchema）——B 覆盖不到它，必须显式点名。
• 与 清空剩余 6 条 authorWarn 死键 —— book ×2 / job.id / translation.validationMessages / app.homePageId / app.areas[].order（ADR-0049，v17 限时） #4667 的一致性说明：清空剩余 6 条 authorWarn 死键 —— book ×2 / job.id / translation.validationMessages / app.homePageId / app.areas[].order（ADR-0049，v17 限时） #4667 退役的是零 resolver 的死内联翻译；本单的 map 有活 resolver（pickLocalized，i18n-extract 亦支持）——declared = enforced 同一原则的两个方向，不矛盾。
• 验收：SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068 闸门下 42 条 component-props-invalid（34 label + 8 content）清零；参考文档再生后如实描述两种形状。零 breaking，无需 conversion。

摘 needs-user-decision，转 pm:queue，spec 车道派发。裁决即解锁 #5068 error 升级的本项前置。

---

Generated by Claude Code