Found while implementing #16251, which states both authorized I18nLabel forms on
content/docs/protocol/kernel/i18n-standard.mdx. Filed unassigned and unlabelled —
triage owns domain:* and the grading. This is not a defect in that card's PR:
none of the lines below were edited by it.
The gap
Measured on origin/main at aaacf1d5c5, the same page describes two different,
incompatible bundle-key conventions for the same field, and says of one of them that
it is the only one.
### Object-First Convention (:166), at :174:
There is exactly one shape. A file-authored bundle is a map of locale code →
TranslationData … The resolvers, os i18n extract, os i18n check, and the
Studio editor all read the same keys.
### Orphan Keys and Option Keys then tabulates those keys as objects.{object},
objects.{object}.fields.{field}, objects.{object}._views.{view}, and so on.
## ObjectQL Integration (:730) and ## ObjectUI Integration (:784) teach the
other convention:
:742 label: 'account.label', // Translation key
:748 label: 'account.fields.name', // Translation key
:795 label: 'account.list.title', // Translation key (i18n label)
with a bundle file i18n/en/account.json holding { "label": "Account", "fields": { "name": "Account Name" } } — a flat per-namespace file, not the object-first
objects.account.label the same page declares normative. The prose at :780
asserts:
The raw label value stored on the metadata is the translation key; the rendered
locale is supplied by the request's resolved locale.
Why that sentence is the load-bearing one
packages/spec/src/system/i18n-resolver.ts derives the key from the label's
position, never from its value:
Developers author plain English labels in metadata (*.view.ts, *.actions.ts);
these helpers translate at render time using the standardized keys:
objects.<object>._views.<view_key>.label …
Lookup order: requested locale → each entry of fallbackChain → literal label
from the metadata — except that a request for the deployment's defaultLocale
never walks the chain: the authored label IS the default locale's text (#15711)
The page already states that half itself, at ### Locale Fallback (:155): "the
inline label: authored on the metadata is the default locale's text". So one
page carries both "the authored label IS the default locale's text" and "the raw
label value stored on the metadata is the translation key", about the same field.
What was NOT measured
objectui's translateLabel lives in the sibling repo and was not measured here,
so this card does not claim the examples fail at runtime — only that the page
contradicts itself and its own normative sections. Whoever picks it up should measure
translateLabel first, and then decide which of the two is true: the
ObjectQL/ObjectUI examples need rewriting to the object-first convention, or the flat
convention is a second live route and the "exactly one shape" sentence is the one
that is wrong.
Why it was left out of the #16251 PR
That decision needs the objectui measurement and would rewrite two sections plus their
code samples — outside a card whose subject is the missing second label form. The
#16251 PR repaired only the one adjacent sentence its own addition made
self-contradictory (os i18n check "runs in one direction — which keys the metadata
expects that no bundle carries", which is not how a gap on a map-authored prop is
closed).
Related: #16251, #15984, #14749, #5377.
Found while implementing #16251, which states both authorized
I18nLabelforms oncontent/docs/protocol/kernel/i18n-standard.mdx. Filed unassigned and unlabelled —triage owns
domain:*and the grading. This is not a defect in that card's PR:none of the lines below were edited by it.
The gap
Measured on
origin/mainataaacf1d5c5, the same page describes two different,incompatible bundle-key conventions for the same field, and says of one of them that
it is the only one.
### Object-First Convention(:166), at:174:### Orphan Keys and Option Keysthen tabulates those keys asobjects.{object},objects.{object}.fields.{field},objects.{object}._views.{view}, and so on.## ObjectQL Integration(:730) and## ObjectUI Integration(:784) teach theother convention:
with a bundle file
i18n/en/account.jsonholding{ "label": "Account", "fields": { "name": "Account Name" } }— a flat per-namespace file, not the object-firstobjects.account.labelthe same page declares normative. The prose at:780asserts:
Why that sentence is the load-bearing one
packages/spec/src/system/i18n-resolver.tsderives the key from the label'sposition, never from its value:
The page already states that half itself, at
### Locale Fallback(:155): "theinline
label:authored on the metadata is the default locale's text". So onepage carries both "the authored label IS the default locale's text" and "the raw
label value stored on the metadata is the translation key", about the same field.
What was NOT measured
objectui's
translateLabellives in the sibling repo and was not measured here,so this card does not claim the examples fail at runtime — only that the page
contradicts itself and its own normative sections. Whoever picks it up should measure
translateLabelfirst, and then decide which of the two is true: theObjectQL/ObjectUI examples need rewriting to the object-first convention, or the flat
convention is a second live route and the "exactly one shape" sentence is the one
that is wrong.
Why it was left out of the #16251 PR
That decision needs the objectui measurement and would rewrite two sections plus their
code samples — outside a card whose subject is the missing second label form. The
#16251 PR repaired only the one adjacent sentence its own addition made
self-contradictory (
os i18n check"runs in one direction — which keys the metadataexpects that no bundle carries", which is not how a gap on a map-authored prop is
closed).
Related: #16251, #15984, #14749, #5377.