Observation, filed rather than fixed. Found while implementing #14253; left alone deliberately — rest-server.ts is one of the hottest files in the repo and a one-word comment edit is not worth the conflict risk on a diff that already touches it elsewhere.
What
packages/rest/src/rest-server.ts:2963, inside translateMetaItem, explains the #6349 singular/plural normalization and illustrates it with a hand-written enumeration of the set:
…those are singular-only (view/action/object/app/dashboard/page), matching translateMetadataDocument's "Canonical metadata type string".
#14253 registers translateDataset in METADATA_DOCUMENT_TRANSLATORS, so the real set is now seven, and this parenthetical is six.
Why it is worth a card at all
Nothing breaks — the code reads TRANSLATABLE_METADATA_TYPES, which is derived, and the derivation is exactly what makes registering a translator a one-edit change (#3786). The enumeration is illustrative.
But it is a hand-maintained copy of a derived set sitting next to the code that reads the derived set, and this repo's own record is that a reader who trusts a restated list cannot see what it is missing — the reason TRANSLATABLE_META_TYPES stopped being hand-copied here in the first place, and the reason the skills catalog is browsed rather than listed. The comment's actual point is "these spellings are SINGULAR", which does not need the full set to make.
Two ways to close it
- Drop the enumeration and keep the point: "…those are singular-only, matching
translateMetadataDocument's 'Canonical metadata type string'". No list, nothing to rot.
- Keep an example and mark it as one (
e.g. \view` not `views``).
Preference is (1) — an illustrative list that must be maintained is the worst of both.
Not in scope here
packages/spec/src/conversions/registry.ts:3039 carries a similar sentence, and it should be left as it is: it is the recorded historical rationale for the 17.0.0 book.translations retirement, describing the state at the time of that removal. Rewriting a retirement's justification to match today's set would be the opposite mistake.
Observation, filed rather than fixed. Found while implementing #14253; left alone deliberately —
rest-server.tsis one of the hottest files in the repo and a one-word comment edit is not worth the conflict risk on a diff that already touches it elsewhere.What
packages/rest/src/rest-server.ts:2963, insidetranslateMetaItem, explains the #6349 singular/plural normalization and illustrates it with a hand-written enumeration of the set:#14253 registers
translateDatasetinMETADATA_DOCUMENT_TRANSLATORS, so the real set is now seven, and this parenthetical is six.Why it is worth a card at all
Nothing breaks — the code reads
TRANSLATABLE_METADATA_TYPES, which is derived, and the derivation is exactly what makes registering a translator a one-edit change (#3786). The enumeration is illustrative.But it is a hand-maintained copy of a derived set sitting next to the code that reads the derived set, and this repo's own record is that a reader who trusts a restated list cannot see what it is missing — the reason
TRANSLATABLE_META_TYPESstopped being hand-copied here in the first place, and the reason the skills catalog is browsed rather than listed. The comment's actual point is "these spellings are SINGULAR", which does not need the full set to make.Two ways to close it
translateMetadataDocument's 'Canonical metadata type string'". No list, nothing to rot.e.g. \view` not `views``).Preference is (1) — an illustrative list that must be maintained is the worst of both.
Not in scope here
packages/spec/src/conversions/registry.ts:3039carries a similar sentence, and it should be left as it is: it is the recorded historical rationale for the 17.0.0book.translationsretirement, describing the state at the time of that removal. Rewriting a retirement's justification to match today's set would be the opposite mistake.