Skip to content

Commit 1c6f7b4

Browse files
os-justinclaude
andauthored
docs(spec): record why element:text's content is not a PageTranslation.components key (#15216)
* docs(spec): record why `element:text`'s `content` is off the page-component translation face `PageTranslation.components` names its deliberate exclusions with reasons — `help` because no component declares it, `subtitle` because `page:header` is addressed by page name. `content` was neither named nor excluded, so an author looking for a bundle key for the one string `element:text` renders found an absence that reads exactly like an oversight. It is not one. `element:text` declares `content: I18nLabelSchema` (`ui/component.zod.ts`), localizable at its own authoring site, so adding it to this face would be the face widening the `submitLabel` retirement declined for the identical shape (#10926). Written down beside the other two, citing that precedent, and pointing the separate extraction/coverage question at #14749. Comment only: no schema key, no `describe()`, no resolver change. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk * chore(changeset): patch for the `element:text` `content` exclusion note `@objectstack/spec` publishes `src/**/*.zod.ts` in its npm `files`, so the edited comment ships in the tarball verbatim (and the text also lands in `dist/browser/**`). The diff therefore publishes from a released package, which is exactly what `skip-changeset` is NOT for. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 3933819 commit 1c6f7b4

2 files changed

Lines changed: 24 additions & 2 deletions

File tree

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
"@objectstack/spec": patch
3+
---
4+
5+
docs(spec): `PageTranslation.components` now says why `element:text`'s `content` is not one of its keys (#14412)
6+
7+
The per-component translation face names its deliberate exclusions with reasons — `help` because no component in the model declares it, `subtitle` because `page:header` is already addressed by page name. `content` was neither named nor excluded. An author looking for a bundle key for the one string `element:text` renders therefore found an absence, and an absence reads exactly like an oversight.
8+
9+
It is not one, and the schema comment now records that beside the other two. `element:text` declares `content: I18nLabelSchema` (`ui/component.zod.ts`), so the string is localizable at its own authoring site as an inline `{ en, 'zh-CN' }` locale map — the route `sys-user.page.ts` itself uses. Adding it to the bundle face would be the face widening the `submitLabel` retirement declined for the identical shape (#10926, ADR-0049).
10+
11+
No key was added and no behaviour changed: the bundle face is still `title` / `description` / `label` / `placeholder` / `emptyText`, and `translatePage` resolves exactly what it resolved before. Bundles, extractor output and existing page definitions are unaffected.
12+
13+
Known and tracked separately: inline locale maps are invisible to `os i18n extract` and `check:i18n-coverage`, so page prose written this way is not counted by coverage tooling. That is true of every inline `I18nLabel` field rather than this component alone, and is carried as #14749.

packages/spec/src/system/translation.zod.ts

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -875,8 +875,9 @@ const translationDataShape = () => ({
875875
* `translation-component-submit-label-removed` conversion strips the key
876876
* from stored bundles.
877877
*
878-
* Two deliberate exclusions, both of which a mirror of the issue's proposed
879-
* shape would have got wrong:
878+
* Three deliberate exclusions — the first two because a mirror of the
879+
* issue's proposed shape would have got them wrong, the third because the
880+
* key was asked for and declined:
880881
*
881882
* - **`help` is not here** — no component in the model declares it. It
882883
* would parse clean and translate nothing, which is the ADR-0078 shape
@@ -886,6 +887,14 @@ const translationDataShape = () => ({
886887
* that component is addressed by page name above. Declaring it in both
887888
* places would give one string two spellings, which is how the
888889
* dashboards/pages asymmetry started.
890+
* - **`content` is not here** — `element:text`'s one authored string is
891+
* declared `content: I18nLabelSchema` (`ui/component.zod.ts`), so it is
892+
* localizable at its own authoring site, and adding it to this face would
893+
* be the face widening the `submitLabel` retirement declined for the
894+
* identical shape (#10926). The inline locale map is the ruled route for
895+
* page prose, not a workaround. That such maps are invisible to
896+
* `os i18n extract` and `check:i18n-coverage` is real, and is its own
897+
* question about the extractor (#14749) rather than a second key here.
889898
*
890899
* `properties` is an open record and custom component types are legal, so
891900
* these keys are also the route for a bespoke component that speaks the

0 commit comments

Comments
 (0)