i18n: give bulk-action defs, custom validation messages and dataset labels a bundle key

[os-warren]

Fixes #14253

Note: key placeholders below are written OBJECT / VIEW / RULE / NAME / DIM / MEASURE / PARAM
rather than in angle brackets — GitHub's body sanitizer strips angle-bracket-shaped fragments, which is what
ate them on the first revision of the issue this closes.

Three authored display surfaces carried user-facing text that no key in TranslationDataSchema could reach — not a drifted key, no key. Each rendered in the source locale inside an otherwise fully translated screen, which is the bad failure mode: it reads as a styling quirk rather than as a missing translation.

Purely additive. Three new translation groups, one new dispatch-table entry, one new lookup on the write path, one localization step at the analytics door. No existing key changes shape, no resolution order changes, and every surface still falls back to the authored literal when the bundle carries nothing.

Five commits, one per surface plus two the work turned up.

---

1 · bulkActionDefs on a list view

objects.OBJECT._views.VIEW.bulkActions.NAME.{label,confirmText,confirmLabel,params.PARAM.{label,help,placeholder}}, resolved in translateView against config.bulkActionDefs.

A bulk-action def is part of the view document, not an action document, so it never reached translateAction. The selection bar read 已选择 1 项 · Complete · Skip · 清除.

config is the one address a served def has — both ViewItemSchema and expandViewContainer nest the whole ListView under config — so the fixture is derived from the composer rather than transcribed, the #4854 lesson one level in.

The def's label deliberately stays a plain z.string() on the authoring side: ui/bulk-action.zod.ts's module header measured that the bar renders it as a React child, so an inline locale map would be a blank cell rather than a parse error. Overlaying at the metadata boundary keeps the wire value a plain string and changes only its language. The documented alternative (bulkActions: ['NAME'], promoting a declared action) is not equivalent: it is N elevated per-record dispatches instead of one data-plane updateMany.

2 · A custom validation rule's message

objects.OBJECT._validations.RULE.message, spelled by the new objectValidationMessageKey and read on the write path by a new authoredRuleMessage seat in the rule evaluator.

⚠️ This adds a key shape, not a channel. The lookup runs on the existing ValidationMessageContext.translate hook — the engine's i18nService, bridged by ObjectQLPlugin — that resolveFieldLabel and renderValidationMessage have used since #3957. Before it, a deployment read platform-generated refusals in the caller's language and author-written refusals in the source language inside one 400 VALIDATION_FAILED envelope.

All five authored-message emitters route through the one seat (script/cross_field, state_machine, format, and both json_schema arms). A nested conditional branch is addressed by the branch's own name; the wrapping conditional's message never reaches a caller. A PLATFORM-generated rejection (an unevaluable predicate) is deliberately left alone — the caller needs to be told the rule is broken, not told the rule's verdict.

This is not validationMessages coming back. That group (retired 17.0.0, #4667, ADR-0049) was keyed by rule name at the bundle's top level, so it could not tell two objects' rules apart, and — the reason it was retired — nothing read it. Its ADR-0087 conversion still strips it from stored bundles, untouched. The replacement is object-scoped, sits beside _views/_actions/_tabs, and ships its reader in the same change. Its tombstone and the errors tombstone now point at it instead of asserting no route exists.

messages['validation.field.*'] is unchanged and still overrides the built-in field catalog only.

3 · Dataset labels — and the door the dashboard actually draws through

datasets.NAME.{label,description,dimensions.DIM.label,measures.MEASURE.label} plus translateDataset in METADATA_DOCUMENT_TRANSLATORS. Registering the translator is the whole wiring: TRANSLATABLE_METADATA_TYPES is derived from that table and @objectstack/rest reads the derived set (#3786). No second hand-maintained list exists — the derivation is intact; the one historical hand-copy in rest-server.ts was already retired.

Top-level rather than nested under dashboards because a dataset is the ONE definition every presentation binds to by reference (ADR-0021 D1): the same measure is drawn by N widgets across M dashboards, and a dataset no dashboard references would otherwise be unaddressable.

The fifth commit exists because translateDataset alone would not have fixed the screenshot. AnalyticsResult.fields[].label is documented as the display label "for legends/KPIs", and AnalyticsService fills it by copying dataset.measures[].label off the definition. That definition arrives through POST /analytics/dataset/query, which resolves a saved dataset via getMetaItems and never passes through translateMetaItem. So the metadata read was the door a dashboard does not draw through — covered at one door, open at the other. The saved definition now goes through the existing translateMetaItem before it is parsed and compiled, and the existing enrichment carries the translated label to the wire untouched: nothing downstream learns about bundles, the analytics service stays free of i18n, and there is no second resolution path. ⛔ The inline branch is deliberately not translated — a Studio preview posts the draft the designer is editing, which carries no saved name to address a bundle entry with. Pinned both ways.

---

Key faces are measured, not mirrored

Nothing here parses clean and translates nothing. Every exclusion carries guidance naming the right home:

excluded	why, measured
bulk param options	BulkActionParamSchema.options[].value is string | number | boolean, so a value-keyed map cannot address true and "true" apart — the same reason FLOW_SCREEN_FIELD_NO_OPTIONS gives
bulk def successMessage	a def declares none; the run reports a per-record outcome summary the console words itself
validation label / description	the admin rule-listing entry and the administrative note — neither reaches a rejected caller
dataset dimension/measure description	dataset.zod.ts already tells authors "its author-facing text is label. description is declared on the DATASET itself"

And a bulk param's hint is help, not the action-param helpText — the face follows the authored key and aliases the neighbouring spelling onto it, so one string keeps one address.

---

Verification

Union re-run after the final commit, at e865543fe (git rev-parse --short HEAD), which includes the merge of origin/main @ 72adb7fcb.

Red-first, per surface — each proved by committing the fix, restoring the source from origin/main/HEAD~1 (tree only), confirming the reversion on disk with an anchored grep -c, and re-running:

surface	reverted	result
1 · bulkActionDefs	i18n-resolver.ts + translation.zod.ts	10 failed / 190 passed
2 · validation messages	rule-validator.ts only	3 failed / 180 passed
3 · datasets (metadata door)	i18n-resolver.ts + translation.zod.ts	10 failed / 210 passed
3b · datasets (analytics door)	rest-server.ts only	1 failed / 12 passed

Each reversion was confirmed by grep before the run (authoredRuleMessage: 0, message: rule.message: 5, translateDataset: 0, translateMetaItem(req, 'dataset': 0) and each restoration confirmed the same way afterwards, with git status --porcelain empty.

Suites — pnpm --filter PKG test / typecheck, all at the merged head: @objectstack/spec 12 103 passed / 450 files · @objectstack/objectql 4 398 passed / 254 files · @objectstack/rest 2 805 passed / 167 files. Typechecks green for all three.

Gates — node scripts/pm/dispatch-gates.mjs --commands derives 78 families for this diff (74 by path + 7 by kind, 3 shared). All 78 run at e865543fe: 76 green, 2 NOT MEASURED — check-test-completeness and check:pm-half-states, both exit 3 ("nothing was measured", distinct from a finding's 1): the first needs a saved turbo run test log, the second needs the GitHub PM board. Neither is a finding and neither is evidence about this tree.

pnpm lint (eslint . --no-inline-config, whole repo) green — no narrowing to declare. check:nul-bytes green, plus a direct control-byte scan over every file in the diff.

Two gates were red on first run and are worth recording rather than hiding: check:doc-authoring caught two #NNNN citations this branch had written into customer-facing tombstone text (printed verbatim at an author whose reader has no tracker — maintainer ruling 2026-08-12), and five spec gates refused on a stale dist. The first is commit 4, which also adds the negative pin the gate's own remedy asks for; the second was a rebuild.

External acceptance — measured from outside the platform

objectstack-ai/duly records all three surfaces as declared, reasoned exemptions in src/translations/authored-text.ts, and its i18n gate anchors them on the platform's own answer. Run at dd3c619 with node_modules/@objectstack/spec repointed at this branch's build (an untracked symlink, restored immediately and verified):

baseline (published 17.2.0)   29 passed
against this branch            1 failed | 28 passed

  × pins the metadata types the PLATFORM says are translatable
    the platform's translatable metadata types changed — re-derive the
    `untranslatable` verdicts in src/translations/authored-text.ts
    expected [ 'action', 'app', 'dashboard', …(4) ]
      to deeply equal [ 'action', 'app', 'dashboard', …(3) ]

TRANSLATABLE_METADATA_TYPES now reads ["action","app","dashboard","dataset","object","page","view"].

Stated plainly, because it is one of two mechanisms and not both: duly's gate has a platform-derived pin (that set) and an app-side pin (an exact list of exemption paths, plus a staleness check). Only the platform-derived pin goes red here, which is the correct behaviour — the exemption-staleness check cannot fire until duly's own walk starts emitting the new keys, since its authored strings are unchanged. So this is end-to-end proof that the platform's answer moved, not proof that duly's three exemptions have been retired; retiring them is duly's follow-up.

---

Out of scope, filed

• i18n-extract scaffolds none of the three key families #14253 adds, so check:i18n-coverage is blind to them #14376 — the i18n extractor does not emit the three new key families (packages/cli/src/utils/i18n-extract.ts) — so os i18n extract will not scaffold them and check:i18n-coverage is blind to them. Deliberately separate: it moves nine generated bundles and scripts/i18n-coverage-baseline.json, and that ratchet movement should be readable on its own. Zero platform bundles change today (no extracted package ships a bulkActionDefs, a validations[].message or a dataset).
• Published skill objectstack-i18n teaches that validation messages are not a translation group — false once #14253 lands #14377 — skills/objectstack-i18n/SKILL.md teaches "Validation messages are not a translation group" — now false. skills/** is a governed surface (Prime Directive feat: Comprehensive CRM example demonstrating all ObjectStack protocol features #14), so it may not ride a mixed diff.
• translateMetaItem's comment restates the translatable-type set by hand, so it goes stale every time the dispatch table grows #14378 (finding) — rest-server.ts:2963 carries an illustrative parenthetical enumerating the translatable set by hand, which this change makes short by one. Left alone deliberately: a one-word comment edit is not worth the conflict risk in that file.

Notes for the reviewer

• Liveness: datasets is seeded live and drilled (label / description / dimensions / measures) with its reader in the same change, not declared first and wired later. Two stale ledger sentences were corrected with it — the translation header still called validationMessages "the one dead group" a major version after 清空剩余 6 条 authorWarn 死键 —— book ×2 / job.id / translation.validationMessages / app.homePageId / app.areas[].order（ADR-0049，v17 限时） #4667 removed it, and validation.message's note still named validationMessages as the override route.
• _validations and _views.VIEW.bulkActions sit beneath the ledger's walk boundary, so neither adds a row; check:liveness confirms.
• Merged origin/main @ 72adb7fcb. The only overlapping file is packages/objectql/src/validation/rule-validator.ts (main's stripReadonlyFields uses Object.is to tell a hook write from a caller write, so a hook cannot clear a readonly field the caller also sent as null #14088 hookWrittenKeys work, in a different region); both sides verified present after the merge, and no merge=os-regen path was touched by both sides, so the driver's silent-drop hazard did not arise. check:generated reports all 15 artifacts current post-merge.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SqkTcrxUFci7nqXdbBSe2p

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/lint, @objectstack/objectql, @objectstack/rest, @objectstack/spec, touching 50 documentable anchor(s). ⚠️ 7 changed file(s) yielded no anchor (packages/spec/api-surface/system.json, packages/spec/authorable-surface/system.json, packages/spec/export-origins/system.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

36 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 5c9e40ad91028b57b0748e3ea0347189bac72ce9.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 7 changed file(s) yielded no anchor (packages/spec/api-surface/system.json, packages/spec/authorable-surface/system.json, packages/spec/export-origins/system.json, …) — pages documenting those are invisible to this run
• 7 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 130 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 5c9e40ad91028b57b0748e3ea0347189bac72ce9 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from f4fc60591e522fdb0b8c368bb7eb2d4610723f84 — the merge of head 7b1c387bb3769c44f03b6c8b79757d62d98960f2 into base 5c9e40ad91028b57b0748e3ea0347189bac72ce9, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin f4fc60591e522fdb0b8c368bb7eb2d4610723f84 && git checkout f4fc60591e522fdb0b8c368bb7eb2d4610723f84
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 5c9e40ad91028b57b0748e3ea0347189bac72ce9 7b1c387bb3769c44f03b6c8b79757d62d98960f2 && git checkout -B drift-repro 5c9e40ad91028b57b0748e3ea0347189bac72ce9 && git merge --no-ff 7b1c387bb3769c44f03b6c8b79757d62d98960f2

node scripts/docs-audit/affected-docs.mjs --json 5c9e40ad91028b57b0748e3ea0347189bac72ce9

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 5c9e40ad91028b57b0748e3ea0347189bac72ce9 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-warren]

PM review — the open question is settled as A, and one claim in this PR is deliberately not being made

The ADR question: land as-is, with the paper trail as a follow-up

Surface 2 gives author-written validation-rule messages a translation route that 17.0.0 closed, and Prime Directive #13 says reversing a recorded decision is itself a decision. The judgement:

This is ADR-0049 being enforced, not reversed. The policy is enforce-or-remove; validationMessages was removed because nothing read it. Shipping a key with its reader in the same commit is the other half of that same policy. Three facts make it not-the-same-key rather than a comeback: the old group was top-level-keyed and could not tell two objects' rules apart, the new one is object-scoped and sits beside _views/_actions/_tabs, and the ADR-0087 conversion that strips the old key from stored bundles is untouched.

Raising it instead of quietly landing it was the right call — a decision recorded in a tombstone rather than an ADR is exactly the shape #13 warns is easy to miss, and the tombstone text does become false with this change.

So: A now, B as a follow-up card, not "later if someone remembers". The whole reason this issue existed is that a governance record living only in prose drifts out of true. I would not accept the same fate for the record of this change. Please file the status-line/ADR card before this merges, blocked-by this PR, so the trail is queued rather than intended.

C is correctly rejected, and for the reason the card gives: it leaves a deployment reading platform refusals in Chinese and author-written refusals in English inside one 400 VALIDATION_FAILED envelope.

The correction to my own scoping is the most valuable thing here

I scoped surface 3 as "add translateDataset, register it in the table, done" and said the derivation would carry it to the REST boundary for free. That would have shipped a fix that did not fix the screenshot. AnalyticsResult.fields[].label is filled by copying dataset.measures[].label off the definition, and that definition arrives via POST /analytics/dataset/query → getMetaItems, which never passes through translateMetaItem. Covered at one door, open at the other — and the door I named is not the one a dashboard draws through. Finding that instead of implementing my prescription is the difference between this PR working and it looking like it worked.

What is NOT proven yet, and I want that on the record before review

The external-acceptance section is scrupulous about this and I am restating it so no reviewer reads past it: the red test in duly proves the platform's answer moved, not that the screenshot is fixed. Only the platform-derived pin fires. The measure labels on that dashboard will still render English after this merges, because duly's zh-CN bundle carries no datasets.* keys yet — its authored strings are unchanged.

The visual proof needs both halves. I have filed objectstack-ai/duly#106 for the application side (retire the three exemptions, author the keys, re-take the two screenshots in this issue), blocked on this PR shipping in a release. Until that lands, this PR's claim is "the route exists and is read", which is exactly what its tests show.

Marking ready for review. Not merging: needs:contract-review + protocol:system, and a system-protocol change is not mine to land.

---

Generated by Claude Code

[os-warren]

CI red root-caused and fixed — 7b1c387bb

Test Core (3/6) failed on one pin in @objectstack/lint:

validate-translation-references.test.ts:1514
  classifies every key `ObjectTranslationDataSchema` declares, and no key it does not
  expected [ …8 ] to deeply equal [ …9 ]      ← "_validations"

That pin reads the schema's .shape and demands the lint rule classify every group with a working leg. This PR added the _validations group to the schema and no leg to the rule — exactly the "a second hand-maintained enumeration drifted" defect class this PR exists to close, caught by the guard built for it. Right failure, right place.

The fix is what the pin asks for, in the rule's own idiom: the walker now registers objects[].validations[].name per object, and reports translation-target-unknown for a _validations key naming a rule the object does not declare, with the same guidance shape as _tabs. The coverage pin and the all-real-names control both carry the group, and the fixture declares one rule so the control is non-vacuous. @objectstack/lint added to the changeset as a patch — a new finding is a user-visible behaviour of a published package.

Verified locally before pushing, on the PR head with spec, formula and sdui-parser built (the fresh worktree's first run showed 33 file failures that were all Failed to resolve entry for package "@objectstack/formula" — unbuilt siblings, not the change; recorded so nobody chases it):

@objectstack/lint test      Test Files 93 passed (93) · Tests 2715 passed | 5 skipped
@objectstack/lint typecheck 0 errors

Nothing else in the PR changed. Subscribed to this PR's CI; I will act on the next red rather than wait to be asked.

---

Generated by Claude Code