fix(spec): translateAction overlays an action's description and its param dialog copy

.changeset/action-description-and-params-translation.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): an action's `description` and its parameter dialog now honour the translation bundle
+
+`translateAction` overlaid only `label`, `confirmText`, `successMessage` and
+`resultDialog`. The keys for the rest were already there — the translation
+schema declares `_actions.ACTION.description` and
+`_actions.ACTION.params.PARAM.{label, helpText, placeholder, options}`, and the
+translation linter validates both, reporting a parameter key the action does not
+declare with a did-you-mean naming the ones it does. So the keys parsed, they
+linted, and they resolved to nothing: a translated deployment rendered a
+translated action button that opened an untranslated form, because an action's
+`description` is the explanatory line under the dialog title and its
+parameters' `label` / `helpText` / `placeholder` / option labels are the rest of
+that dialog.
+
+They are applied now, wherever the action is served — the REST metadata read,
+OpenAPI, MCP — and through `globalActions` for an action that belongs to no
+object, the same object-scoped-first order every other action key already used.
+
+Parameters are matched by `name`, falling back to `field` for a field-backed
+parameter that names no key of its own: the same rule the linter collects
+parameters by, so a key the linter accepts is a key the resolver finds. Option
+labels are matched on the stored option `value`, since the authored side is an
+array of options while the translation side is a `value` to label map.
+
+Nothing changes for a bundle that carries none of these keys: the authored text
+is kept, the parameter array keeps its identity, and a bundle key naming a
+parameter the action does not declare is ignored rather than invented into the
+dialog. No schema, no validator and no accepted shape moves — every key applied
+here was already declared and already validated.

packages/spec/api-surface/system.json

@@ -7,6 +7,7 @@
     "AccessControlConfigParsed (type)",
     "AccessControlConfigSchema (const)",
     "ActionLike (interface)",
+    "ActionParamLike (interface)",
     "ActionResultDialogTranslation (type)",
     "ActionResultDialogTranslationSchema (const)",
     "AddFieldOperation (const)",

packages/spec/export-origins/system.json

@@ -7,6 +7,7 @@
     "AccessControlConfigParsed": "src/system/object-storage.zod.ts#AccessControlConfigParsed (type)",
     "AccessControlConfigSchema": "src/system/object-storage.zod.ts#AccessControlConfigSchema (const)",
     "ActionLike": "src/system/i18n-resolver.ts#ActionLike (interface)",
+    "ActionParamLike": "src/system/i18n-resolver.ts#ActionParamLike (interface)",
     "ActionResultDialogTranslation": "src/system/translation.zod.ts#ActionResultDialogTranslation (type)",
     "ActionResultDialogTranslationSchema": "src/system/translation.zod.ts#ActionResultDialogTranslationSchema (const)",
     "AddFieldOperation": "src/system/migration.zod.ts#AddFieldOperation (const)",

packages/spec/src/system/i18n-resolver.test.ts

@@ -464,6 +464,173 @@ describe('resolveActionResultDialog + translateAction', () => {
   });
 });
 
+describe('translateAction — description + params (the declared-and-linted keys)', () => {
+  // The card's own zh-CN fixture: `TranslationItemSchema` declares every key
+  // below and the translation linter validates them, so this bundle is what an
+  // author writes today and expects to render.
+  const bundle: TranslationBundle = {
+    'zh-CN': {
+      objects: {
+        duly_task: {
+          _actions: {
+            duly_task_skip: {
+              label: '跳过',
+              description: '动作描述',
+              confirmText: '确认',
+              successMessage: '已跳过',
+              params: {
+                skip_reason: {
+                  label: '原因',
+                  helpText: '帮助',
+                  placeholder: '占位',
+                  options: { too_late: '太晚了' },
+                },
+                // A key the action does NOT declare — the linter reports it
+                // (`checkActionParams`); the resolver must ignore it.
+                nonexistent_param: { label: '幽灵' },
+              },
+            },
+          },
+        },
+      },
+      globalActions: {
+        export_secrets: {
+          description: '导出所有密钥',
+          params: { format: { label: '格式', helpText: '导出格式' } },
+        },
+      },
+    },
+  };
+
+  const skip = {
+    name: 'duly_task_skip',
+    label: 'Skip',
+    description: 'D',
+    objectName: 'duly_task',
+    confirmText: 'Sure?',
+    successMessage: 'Skipped',
+    params: [
+      {
+        name: 'skip_reason',
+        label: 'Why skipped',
+        helpText: 'H',
+        placeholder: 'P',
+        options: [
+          { value: 'too_late', label: 'Too late' },
+          { value: 'duplicate', label: 'Duplicate' },
+        ],
+      },
+    ],
+  };
+
+  it('overlays the action description', () => {
+    expect(translateAction(skip, bundle, { locale: 'zh-CN' }).description).toBe('动作描述');
+  });
+
+  it('keeps the authored description when the bundle carries none', () => {
+    const out = translateAction(skip, bundle, { locale: 'ja-JP', fallbackChain: [] });
+    expect(out.description).toBe('D');
+    // Source document is not mutated.
+    expect(skip.description).toBe('D');
+  });
+
+  it('overlays a param label', () => {
+    expect(translateAction(skip, bundle, { locale: 'zh-CN' }).params?.[0].label).toBe('原因');
+  });
+
+  it('overlays a param helpText — the ACTION spelling, not the bulk `help`', () => {
+    const out = translateAction(skip, bundle, { locale: 'zh-CN' });
+    expect(out.params?.[0].helpText).toBe('帮助');
+    // The bulk-action spelling must not appear on an action param.
+    expect(out.params?.[0]).not.toHaveProperty('help');
+  });
+
+  it('overlays a param placeholder', () => {
+    expect(translateAction(skip, bundle, { locale: 'zh-CN' }).params?.[0].placeholder).toBe('占位');
+  });
+
+  it('overlays param options by stored value, leaving untranslated entries alone', () => {
+    const out = translateAction(skip, bundle, { locale: 'zh-CN' });
+    expect(out.params?.[0].options).toEqual([
+      { value: 'too_late', label: '太晚了' },
+      { value: 'duplicate', label: 'Duplicate' },
+    ]);
+    // Source options are not mutated.
+    expect(skip.params[0].options[0].label).toBe('Too late');
+  });
+
+  it('keeps the authored param copy when the bundle carries none', () => {
+    const out = translateAction(skip, bundle, { locale: 'ja-JP', fallbackChain: [] });
+    expect(out.params?.[0]).toEqual(skip.params[0]);
+    // Nothing changed, so the array itself is the authored one (same reference).
+    expect(out.params).toBe(skip.params);
+  });
+
+  it('matches a field-backed param by `field` when it declares no `name`', () => {
+    const fieldBacked = {
+      name: 'duly_task_skip',
+      objectName: 'duly_task',
+      params: [{ field: 'skip_reason', label: 'Why skipped' }],
+    };
+    const out = translateAction(fieldBacked, bundle, { locale: 'zh-CN' });
+    expect(out.params?.[0].label).toBe('原因');
+  });
+
+  it('prefers `name` over `field` when both are present', () => {
+    const both = {
+      name: 'duly_task_skip',
+      objectName: 'duly_task',
+      // `field` names the translated param; `name` is the key the linter
+      // collects, so the untranslated `name` must win and nothing overlays.
+      params: [{ name: 'other_key', field: 'skip_reason', label: 'Why skipped' }],
+    };
+    const out = translateAction(both, bundle, { locale: 'zh-CN' });
+    expect(out.params?.[0].label).toBe('Why skipped');
+  });
+
+  it('ignores a bundle param the action does not declare', () => {
+    const out = translateAction(skip, bundle, { locale: 'zh-CN' });
+    expect(out.params).toHaveLength(1);
+    expect(JSON.stringify(out.params)).not.toContain('幽灵');
+  });
+
+  it('resolves description and params through globalActions for object-less actions', () => {
+    const out = translateAction(
+      {
+        name: 'export_secrets',
+        label: 'Export secrets',
+        description: 'Export every secret',
+        params: [{ name: 'format', label: 'Format', helpText: 'File format' }],
+      },
+      bundle,
+      { locale: 'zh-CN' },
+    );
+    expect(out.description).toBe('导出所有密钥');
+    expect(out.params?.[0].label).toBe('格式');
+    expect(out.params?.[0].helpText).toBe('导出格式');
+  });
+
+  it('leaves an action with no params untouched', () => {
+    const out = translateAction(
+      { name: 'duly_task_skip', objectName: 'duly_task', label: 'Skip' },
+      bundle,
+      { locale: 'zh-CN' },
+    );
+    expect(out).not.toHaveProperty('params');
+  });
+
+  it('reaches an inline action through translateObject', () => {
+    const out = translateMetadataDocument(
+      'object',
+      { name: 'duly_task', actions: [skip] },
+      bundle,
+      { locale: 'zh-CN' },
+    );
+    expect(out.actions[0].description).toBe('动作描述');
+    expect(out.actions[0].params[0].placeholder).toBe('占位');
+  });
+});
+
 describe('translateMetadataDocument', () => {
   it('translates a view document', () => {
     const view = {