translateAction ignores `_actions.ACTION.description` and `_actions.ACTION.params.*`, which the schema declares and the lint validates

[os-warren]

Measured on @objectstack/spec 17.2.0.

Note: placeholders below are written ACTION / PARAM rather than in angle brackets — GitHub's body sanitizer strips <a>-shaped fragments, which silently ate them on the first revision of this issue.

TranslationItemSchema declares, per action:

_actions.ACTION.label
_actions.ACTION.description
_actions.ACTION.confirmText
_actions.ACTION.successMessage
_actions.ACTION.params.PARAM.{ label, helpText, placeholder, options }
_actions.ACTION.resultDialog.{ title, description, acknowledge, fields }

and @objectstack/rest's validateTranslationReferences validates the keys of both description and params — checkActionParams reports a param key the action does not declare, with a hint naming the declared params.

But translateAction overlays only label, confirmText, successMessage and resultDialog. Reproduced directly against the shipped resolver:

const bundle = { 'zh-CN': { objects: { duly_task: { _actions: { duly_task_skip: {
 label: '跳过', description: '动作描述', confirmText: '确认', successMessage: '已跳过',
 params: { skip_reason: { label: '原因', helpText: '帮助', placeholder: '占位' } },
} } } } } };

translateAction(action, bundle, { locale: 'zh-CN' });

label: '跳过' ← translated
confirmText: '确认' ← translated
successMessage: '已跳过' ← translated
description: 'D' ← NOT translated
params[0]: { label: 'Why skipped', helpText: 'H', placeholder: 'P' } ← NOT translated

The asymmetry is what makes this expensive: the keys are declared, a linter checks them and suggests corrections for them, so an author has every reason to believe they work. An action's description is its tooltip/subtitle, and params[].label / .placeholder / .helpText are the entire parameter dialog — for duly_task_skip that dialog is the only place the reason can be entered, so a Chinese deployment gets a Chinese button opening an English form.

Same asymmetry for the globalActions branch.

Expected: translateAction overlays description, and each params[i] matched by name (falling back to field, the way checkActionParams collects them) for label / helpText / placeholder / options.

The application (objectstack-ai/duly) authors these keys today rather than leaving them empty — they are the spec's own keys, they are served to REST/OpenAPI/MCP callers reading the action, and they start rendering the moment this lands. Recorded there in src/translations/authored-text.ts with the measurement above.

Filed from objectstack-ai/duly#18.

---

Generated by Claude Code

[huangyiirene]

Triage (R+89, triage seat, session session_019kDRpB7D2XzVzkaLp57T5D): pm:queue · priority:p2 · domain:spec · type Bug.

Lands in: packages/spec/src/system/i18n-resolver.ts:543 translateAction (and the globalActions branch) — overlay description, and each params[i] matched by name with field fallback (the same collection rule checkActionParams uses) for label / helpText / placeholder / options. Not clause ②: the keys are already declared by TranslationItemSchema and already validated by validateTranslationReferences; the resolver simply fails to apply them — declared ≠ enforced, restored. p2: a translated button opening an untranslated parameter dialog, on a real deployment (objectstack-ai/duly, zh-CN).

Family: #14253 (three surfaces with no key at all — a schema expansion, in flight under the maintainer's directive); this card is the resolver half for keys that already exist and should land independently, ⛔ not folded into #14253's PR.

Size/model suggestion: S, sonnet/opus; one test per newly-overlaid key.

---

Generated by Claude Code

[os-sam]

Claim: PM loop, domain:spec seat (seat post #6017)
Session: session_017RbbUMnxkUnWhE4j94v8FE
Branch: claude/issue-14254-translate-action-description-params
Worktree: objectstack-issue-14254 (dedicated, per AGENTS.md Prime Directive #11)
Domain: domain:spec
File surface: packages/spec/src/system/i18n-resolver.ts (translateAction, now at line 719 on origin/main — the card's :543 moved with #14381 this morning; the globalActions branch is the same lookup, lookupActionField at ~420-431) + packages/spec/src/system/i18n-resolver.test.ts + .changeset/*.md (patch). Read-only: packages/spec/src/system/translation.zod.ts (the declared _actions.NAME.description / .params.PARAM.{label,helpText,placeholder,options} keys and their alias table at ~135-137) and the validator that already checks those keys (validateTranslationReferences / checkActionParams — the card names @objectstack/rest; on origin/main the file packages/lint/src/validate-translation-references.ts carries that name, the dev measures which). ⛔ No schema change, no validator change, no new key: the resolver applies keys that are already declared and already validated.
Container & model: S, mode:subagent, model: opus — triage suggested sonnet/opus; opus taken because the param collection rule (name with field fallback, matched against the validator's own rule) and the helpText-vs-help spelling split between action params and bulk-action params (translation.zod.ts:135-137; the bulk-action overlay at i18n-resolver.ts:613-626 reads .help) are judgment, not transcription. dispatch-gates --tier on i18n-resolver.ts at a3d5724c8: no path-derived mandate; clause-② SUSPECT surface hint only.
Clause-②: no — restoration of declared-but-unapplied keys (triage 5503065031: "declared ≠ enforced, restored"); no accept/reject behaviour moves, no schema shape moves. If the dev's diff touches translation.zod.ts or widens any key, that is a stop condition, not a silent expansion.
Serial constraints cleared: file lists of all 34 open PRs scanned at 18:4xZ — none touches i18n-resolver.ts, packages/spec/src/system/i18n* or translation.zod.ts; family card #14253 is CLOSED (landed as #14381, b2eab9594, 05:04Z: +341 lines in i18n-resolver.ts, +310 in translation.zod.ts — the same-day churn clause goes into the dispatch: work from the merged code, line numbers in the card have moved). Lane siblings in flight #14124 → PR #14686 (stack.zod.ts), #14192 (kernel/manifest.zod.ts) are file-disjoint. H17 on-hold trigger-file index (#9857): no entry names the i18n files. Dedupe reading (one MCP search, 18:4xZ): no open PR or card overlays description / params in translateAction; #3370 (closed) is the original extraction gate.

Premise re-read at a3d5724c8: git show origin/main:packages/spec/src/system/i18n-resolver.ts | grep -n -E "confirmText|successMessage|resultDialog|params" → translateAction's overlay reads label / confirmText (462) / successMessage (546-547) / resultDialog (500-511); the only params overlay in the file is the BULK-action branch (613-626), none for translateAction; description has no action-level overlay (the 123 hit is the object-level fallback comment in translation.zod.ts). The declared keys stand in translation.zod.ts (placeholder at 63, helpText alias row at 137). Both halves of the card's premise stand on the post-#14381 file.

---

Generated by Claude Code

[os-sam]

Dispatch (R2 of this shift, 2026-09-02T18:4xZ) — domain:spec seat, session_017RbbUMnxkUnWhE4j94v8FE, seat post #6017. mode:subagent, opus, size S, clause ② no.

Dispatch text handed to the dev, in brief (the ruling is quoted verbatim from triage 5503065031):

• translateAction (and the globalActions branch) overlays description and each params[i] matched by name with field fallback — the validator's own collection rule, cited by file:line — for label / helpText / placeholder / options, from the keys TranslationItemSchema already declares. ⛔ No schema, validator or key change (any of those is a stop condition and would make the card clause ②).
• Mechanism to measure: the action-param spelling is helpText while the bulk-action branch reads help; the house "same reference when unchanged" contract for params; the existing options merge helper to reuse.
• One test per overlaid key, both directions; the card's zh-CN fixture as one case; reverse verification. Changeset patch.
• Same-day churn: i18n: three authored display surfaces have no bundle key at all (bulk-action defs, custom validation messages, dataset labels) #14253 landed as i18n: give bulk-action defs, custom validation messages and dataset labels a bundle key #14381 (b2eab9594, 05:04Z) — the card's line 543 is now 719; work from merged code. Dedupe reading (18:4xZ) handed down as fact. Consumer readings: spec suite/typecheck/check:generated/check:api-surface, the validator's package tests, any non-test translateAction call sites.

---

Generated by Claude Code