`_views` translation keys have three producers that disagree on the spelling — a default-only `list` container can never resolve

[xuyushun441-sys]

Found while fixing #4854 (the resolver read fields the served document does not have). That fix makes objects.<object>._views.<bare key> resolve for listViews / formViews entries. This issue is the residual: for one common authoring shape the key the extractor writes and the key the runtime identity yields are still different strings, so the translation can never be found no matter which side you author against.

Filed unassigned — recording the finding, not claiming it.

The divergence, measured

Three surfaces derive a _views key, and they do not agree:

surface	file	key it produces for a container's default list
view-document composer (runtime identity)	packages/spec/src/ui/view.zod.ts expandViewContainerWithDiagnostics	<object>.default → bare key default
i18n extractor (writes the bundle skeleton)	packages/cli/src/utils/i18n-extract.ts:453	list
translation-reference lint (validates keys)	packages/lint/src/validate-translation-references.ts collectViewRecord	accepts both the map key and the inner name

Composer:

const key = typeof defaultList.name === 'string' && defaultList.name ? defaultList.name : 'default';

Extractor:

pushViewEntries(out, viewObjectName(view.list) ?? containerObject, view.list.name ?? 'list', view.list);

Measured against the real composer:

container { list: { label: 'All Tasks', type: 'grid', data: { provider: 'object', object: 'task' }, columns: ['title'] } }
composer  -> ["task.default"]     // bare key `default`
extractor -> objects.task._views.list.label

So an app whose object declares only a default list — no listViews — gets a skeleton keyed list, a runtime view keyed default, and an English label on screen forever. It is invisible in examples/app-crm only by luck: its default list is structurally identical to listViews.all, so the composer's signature dedupe collapses the two and the live key becomes all. The _views.list entry in examples/app-crm/src/translations/crm.translation.ts is dead weight that looks correct.

Second, related spelling question

collectViewRecord deliberately accepts a listViews.<key> entry's inner name as a legal _views key ("authors write either"), but the runtime identity for such an entry is derived from the map key only — expandViewContainer never reads the inner name except for the default list/form. So a bundle keyed by the inner name passes lint and resolves to nothing. No view in this repo's own apps carries an inner name, so this is currently theoretical; it is the same contract question one layer over.

Why this needs a decision rather than a patch

Per Prime Directive #12 the cure belongs at the producer, not in resolveViewLabel — teaching the resolver to try default, then list, then config.name would fossilize three dialects for one key and is exactly the consumer-side tolerance the directive bans. The decision is which spelling is canonical:

• A. Canonical = the runtime identity's bare key (default). Extractor changes ?? 'list' → ?? 'default'; lint narrows to the map key / default key; existing bundles with _views.list need a conversion entry or a release note. Pro: one key, derived from the identity the registry actually assigned, and the lint can then enforce it — an AI-authored bundle either matches or is rejected loudly. Con: touches shipped bundles.
• B. Canonical = list. Composer names the default list <object>.list instead of <object>.default. Pro: no bundle churn. Con: default is the registry identity that appears in URLs, overlay rows (sys_metadata), and normalizeViewMetadata baselines — renaming it is a far wider blast radius than renaming a translation key.

Recommendation: A, and tighten collectViewRecord to the same single spelling in the same change, so "declared = enforced" holds for view translation keys.

Repro

pnpm --filter @objectstack/spec build
# then, against src:
node -e "0" # see the measurement snippet above; expandViewContainer('task', { list: {...} }) -> ['task.default']

[xuyushun441-sys]

补一条第四个生产/消费方的证据 —— 这让「统一拼写」的决策范围完整了。

objectui 客户端解析器早已在做同样的剥前缀动作,而且注释把这条约定说得很清楚(objectui 仓库 packages/i18n/src/useObjectLabel.ts:205-221,viewSuffixes):

The runtime uses qualified view ids (objectName 点 viewName) in URLs and metadata records, while translation bundles are keyed by the authored view name under _views.

它先用剥掉对象前缀的短名查,查不到再退回带前缀的全名(候选顺序 [shortViewName, viewName])。

这带来两点:

1. 服务端 fix(spec): 视图标签按运行时真实下发的文档形状解析(#4854) #5165 的修法与客户端既有约定完全一致 —— 都是「以裸键为准,前缀来自注册表身份」。所以本 issue 要统一的不是「服务端该怎么读」,而是生产方(提取器 / lint)写出来的键该是哪一个拼写。
2. 但两端的宽容度目前不对称:objectui 额外接受带前缀的全名作为第二候选,fix(spec): 视图标签按运行时真实下发的文档形状解析(#4854) #5165 的服务端解析只认一个键(刻意为之,避免把第二套方言固化进 spec)。后果是 —— 若某个包按带前缀的键编写,控制台里能显示中文,而 REST 边界返回的仍是英文,移动端 / 纯 HTTP / SDUI 这些不做二次解析的消费方就会看到英文。这正是 i18n: extract + gate declared action/UI labels (they leak English in a zh-CN workspace) #3370 当年那类「只有 Console 对、其他消费方错」的不一致。

所以建议把决策范围从「提取器 + lint」扩到四个面一起收敛到同一个拼写:

• 组装器(运行时身份,expandViewContainer)
• 提取器 pushViewEntries(写骨架)
• lint collectViewRecord(判合法)
• objectui viewSuffixes(客户端二次解析)—— 统一后应当去掉带前缀的第二候选

仍然推荐方案 A(以运行时身份的裸键为准):四个面里已经有三个把裸键当作事实标准,只有默认 list 这一处例外(提取器写 list、组装器命名 default),收敛成本最小,且收敛后 lint 才能真正做到「声明即强制」—— AI 生成的翻译包要么命中,要么被响亮拒绝,而不是悄悄落回英文。

---

Generated by Claude Code