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 = {

.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 = {

.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 = {

.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 = {

.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 = {

.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 = {

.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 = {

.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 = {