Skip to content

Commit 7d0b47c

Browse files
feat(spec): an action param's helpText takes an inline locale map, so an inline action can write its hint per locale (#31485)
<!-- claude-projects-attribution: {"github_login":"os-zhuang"} --> _Requested by **Sam** · [project thread](https://claude.ai/code/project/chan_01GsBogozeZG5sdpAARrN7HP?thread=cmsg_01GsBogozeZG5sdpAARrN7HP5HtnZiicdy84BcZoZeHwXZ)_ Fixes #28266 Clause-②: yes (widening) Metadata-protocol: added Skills-docs: follow-up owed — skills/objectstack-ui/rules/actions.md (its copy-holes line teaches a param's `helpText` as a sentence only; `skills/**` is a Tier H surface, so it is not edited here). This diff teaches the map in `content/docs/protocol/objectui/actions.mdx` (the `ActionParam` fields paragraph) and in the regenerated `content/docs/references/ui/action.mdx`. ## 维护者速读 - 改了什么:动作参数的 `helpText`(参数对话框里输入框下方的说明)现在可以写成按语言的内联映射 `{ en, "zh-CN", … }`,和它旁边的 `label`、`description`、`successMessage` 一样。校验门、控制台解析器和 AI 工具摘要都会按语言读取它。 - 为什么改:cloud 欢迎页的「邀请成员」是页面按钮上的内联动作,没有翻译包可走,标题、说明、选项和提示都写成了多语言映射,唯独角色说明只能是一个英文字符串,所以 cloud 只好把它省掉。注册在对象上的 `invite_user` 本来就经翻译包本地化(7 种语言都已翻好),不需要改。 - 风险与回滚:只放宽接受集,以前能解析的值解析结果不变;回滚即撤销本 PR。 - 先看:`packages/spec/src/ui/action.zod.ts`(`actionParamHelpText` 加上 `localeMap`)、`ui/packages/fields/src/resolveActionParams.ts`(`authoredHelpText`)、`packages/lint/src/validate-action-copy-templates.ts`(逐个语言判句)。 - 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run src/ui/action-copy-template.test.ts`,预期全部通过,其中 helpText 一行是 “keeps inline locale map”。 - 需要你做的:无,席位落地。 ## What changes - **`@objectstack/spec` — `ActionParamSchema.helpText` takes an inline locale map.** `actionParamHelpText` builds the copy family's slot with `{ localeMap: true }`, the option `description`, `confirmText`, `successMessage` and each `outcomeMessages` entry already pass. The slot now accepts a bare sentence, the `{ dialect: 'template', source }` envelope, a blank string (stored rows keep loading) or an `InlineLocaleMapSchema` map. It reaches both carriers of `params`: `ActionSchema` and `InlineActionSchema` (a page button's `properties.action`). Every value that parsed before parses to the same thing. A map whose key is not a language tag is refused with the slot's own sentence, which now also names the map form. - **`@objectstack/lint` — the copy door judges each map entry.** `validate-action-copy-templates.ts` dropped the `key !== 'helpText'` exclusion, so a `helpText` map's entries are judged as sentences at `params[N].helpText.LOCALE`, exactly as a `description` map's are (blank, `${…}`, single-brace token, a hole over a root other than `record`, logic in a hole, unknown formatter: each an error). The i18n walk already files a map as authored text (`authoredEvidence`); only its doc comment changed. - **`@objectstack/runtime` — the agent-facing tool schema reads a map.** `summarizeActionParams` reads `helpText` through a new `paramHelpText`: the string or envelope `source` first, else the map's source-language entry through `resolveI18nLabel` (`en`, then `default`, then any entry). An envelope with no `source` still gives nothing, so the bound field's description stays the fallback. - **`@object-ui/fields` — the console resolves a map for the active language.** `resolveActionParam` narrows `helpText` like `label`: the envelope's `source`, else `resolveI18nLabel(helpText, ctx.locale)`. Before, `actionCopySource(map)` answered `undefined`, so a map fell through to the field's help line. The three branches (inline, unresolved field-backed, field-backed) read the one `authoredHelpText`. - **Docs.** `content/docs/protocol/objectui/actions.mdx` says a param's `helpText` is a sentence translated at `objects.OBJECT._actions.ACTION.params.PARAM.helpText` or an inline locale map, and that the map is how a page button's inline action translates it. `content/docs/references/ui/action.mdx` is regenerated (`gen:docs`). ### Premise reading (the card's facts, re-measured on `main` f67f3b3) - The card says the spec "types action param `helpText` as `string`, so there is no i18n key or per-locale form". The **i18n key exists**: `TranslationItemSchema` declares `_actions.ACTION.params.PARAM.helpText` (`packages/spec/src/system/translation.zod.ts`), the walk emits it (`packages/lint/src/i18n-walk.ts`, `pushActionParams`), `translateActionParams` overlays it server-side (`packages/spec/src/system/i18n-resolver.ts`), and the console overlays it through `actionParamText` (`useConsoleActionRuntime.tsx`, `RecordDetailView.tsx`). - The card's Work item 2 ("translate the `invite_user` role help in the locale packs") is **already done**: the role help (`MEMBERSHIP_ROLE_PARAM_HELP`) sits at 6 sites in `en.objects.generated.ts` (the four `invite_user` mirrors, `sys_member.add_member`, `sys_member.update_member_role`), and each of `ar`, `es-ES`, `fr`, `ja-JP`, `pt-BR`, `zh-CN`, `zh-Hant` carries a translated 5-line help at all 6, with 0 English left. So a zh session on the organization page's registered `invite_user` already reads the role help in Chinese. - The **per-locale form was the real gap**: `helpText` was the one copy slot built without `localeMap` (pinned as "takes no inline locale map" in `action-copy-template.test.ts`). The card's consumer, cloud's welcome page, declares the invitation as an inline `element:button` action with no bundle, writes its label, description, option labels and toast as maps, and leaves `helpText` out on purpose (`packages/service-tenant/src/pages/welcome.page.test.ts`, the comment above `withoutOwner`). This PR closes that gap. ## Tests - `packages/spec/src/ui/action-copy-template.test.ts`: the family table's `params[].helpText` row flips to "keeps inline locale map" (the map parses and is kept; the refusal sentence names the map form); a new describe pins `InlineActionSchema` keeping a field-backed role param's map and refusing a `{ key, defaultValue }` map with the slot's sentence. - `packages/lint/src/validate-action-copy-templates.test.ts`: a map passes; a `${…}` entry and a blank entry are errors at `params[0].helpText.zh-CN` / `.ja-JP` on a registered action; a `result` hole in a page button's inline action map is an error at `· action params[0].helpText.zh-CN`. - `packages/cli/test/i18n-inline-locale-map-coverage.test.ts`: the walk records a `helpText` map at its param key with `inlineLocales`, counts its locales as covered, reports the locale a partial map omits, and scaffolds no bundle row. - `packages/runtime/src/action-param-help-envelope-27948.test.ts`: a map gives its `en` entry (same summary as the bare string), a map with no `en` gives `default`, an empty map falls back to the field description. - `ui/packages/app-shell/src/views/ActionParamDialog.fieldHelpLine-12213.test.tsx`: a zh-CN session draws the map's zh-CN entry under the control, over the field's help; an inline param in a locale the map omits reads `en`; an envelope with no `source` still lends the field's help. <details><summary>Local runs (worktree off main f67f3b3, merged with main c6c2426; final head ea6ad0b)</summary> - `pnpm --filter @objectstack/spec build` → VERDICT command-exit 0. - `pnpm --filter @objectstack/spec test` (head 87e9040, before the main merge; spec did not move on main) → Test Files 822 passed, Tests 26,010 passed, 1 todo. - Targeted, on the final head ea6ad0b: spec `action-copy-template` + `action` + `i18n-resolver` 701/701; lint `validate-action-copy-templates` 26/26; runtime `action-param-help-envelope-27948` 4/4; cli `i18n-inline-locale-map-coverage` 20/20; ui `ActionParamDialog.fieldHelpLine-12213` + `ActionParamDialog.recordHoles-12967` 13/13. - Earlier on 87e9040: lint `validate-action-copy-templates` + `validate-translation-references` 259/259; ui `packages/fields/` whole + six ActionParamDialog / useConsoleActionRuntime / RecordDetailView files → Test Files 306 passed, 1 skipped; Tests 4,640 passed, 7 skipped. - `pnpm --filter @objectstack/lint typecheck`, `pnpm --filter @objectstack/runtime typecheck` → exit 0 (both include `check:test-typecheck`). `pnpm --filter @objectstack/spec check:test-typecheck` → OK (52 files / 240 errors / 131 pinned signatures held). `pnpm --filter @object-ui/fields type-check` (both its programs) → exit 0 after building its dependency closure. `@object-ui/app-shell` type-check (the new dialog cases) is left to `Type Check UI`. </details> <details><summary>Ablations (each mutation through `scripts/ablation-replace.mjs`, anchor 1 → 0, restored to the HEAD blob with `git diff HEAD` empty; every subject resolves through source — a relative import or the ui vitest alias — so no dist leg)</summary> - A1 spec, `actionParamHelpText` built without `localeMap` → `action-copy-template.test.ts` 2 failed / 32 passed: the family row "params[].helpText: keeps inline locale map" and "an inline action … keeping the map". - A2 lint, `sentencesOf(value, localeMap && key !== 'helpText')` → `validate-action-copy-templates.test.ts` 1 failed / 25 passed: "passes a helpText locale map and judges each entry at `.LOCALE`". - A3 runtime, `paramHelpText` map branch returns `undefined` → 2 failed / 2 passed: both #28266 cases; the two #27948 envelope cases stay green. - A4 console, `authoredHelpText` read through `actionCopySource` again → `ActionParamDialog.fieldHelpLine-12213.test.tsx` 2 failed / 8 passed: the zh-CN and the inline-param map cases; the envelope-with-no-source control stays green. </details> ## Acceptance notes - **cloud follow-up (carrier: cloud).** The welcome page's `INVITE_ACTION` can carry the role help as a 4-locale map (`en`, `zh-CN`, `ja-JP`, `es-ES`, copied from the framework bundles like its other copy) once a cloud pin round carries this PR; `welcome.page.test.ts` then compares it to the bundles instead of leaving it out. That is the card's "a zh session sees the role help in Chinese" on the welcome page. - **`summarizeActionParams` reads a param `label` map as absent (observation, not fixed here).** `typeof p.label === 'string' ? p.label : field?.label` gives an inline param with a map label no label in the agent-facing tool schema. Same call site, different key, pre-existing; left for its own card. - **`ActionParamLike.helpText` (`i18n-resolver.ts`) stays typed `string | envelope`,** like its sibling `ActionLike.description`, which also takes a map and is typed the same way. `translateActionParams` passes an authored map through unchanged when no bundle sentence exists, as it does for `description`. Widening both interface types together is a separate, API-surface change. - `check-plugin-teardown-shape --self-test` cannot run on this shallow clone (its positive control is pinned to commit 621a487); NOT MEASURED locally, CI runs it on a full clone. ## Verification <details><summary>Gates</summary> - Derived with `node scripts/pm/dispatch-gates.mjs --commands` at 87e9040 (14 paths vs merge base f67f3b3): 118 families. Run sequentially: 114 exited 0 on the first pass. `check:i18n-walk-parity` exited 3 (workspace CLI not built) and exited 0 after building the CLI closure. Eight gates that overlapped an ablation's mutation window were re-run on the restored tree: all 0. - NOT MEASURED locally (exit 3, prerequisite, nothing read): `check-plugin-teardown-shape --self-test` (positive control pinned to 621a487, unreachable on this shallow clone), `@objectstack/spec check:skill-examples` (needs `packages/client-react/dist`), `check:dual-build-cjs-loads` (needs every package's `dist/`). CI runs all three. `dispatch-gates --ran` → 118 derived, 115 run, 3 UNRUN (those three). - `pnpm --filter @objectstack/spec check:generated`: `check:docs` was stale (regenerated with `gen:docs`, committed); every other artifact up to date. Its `check:test-typecheck` leg died without diagnostics under the shared box's memory, and passed run alone with a 6 GB heap. - i18n: `pnpm check:i18n` → OK (10 packages, all bundles in sync); `pnpm check:i18n-coverage` → OK (14 configs, 426 baselined untranslated, none new); `pnpm check:i18n-walk-parity` → OK (16 declared groups, 14 walked, 2 exempted). - Repo-wide `pnpm lint` and the full battery are CI's. </details> ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` passes (CI-owned repo scan). - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: its generated artifacts are regenerated and committed. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English. --- _Generated by [Claude Code](https://claude.ai/code/session_01QUs3Bt3CmnAuRftY9mRSs2)_ --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: objectstack-fleet[bot] <332303061+objectstack-fleet[bot]@users.noreply.github.com>
1 parent 76e4c2c commit 7d0b47c

14 files changed

Lines changed: 273 additions & 32 deletions
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
'@objectstack/spec': minor
3+
'@objectstack/lint': patch
4+
'@objectstack/runtime': patch
5+
'@object-ui/fields': patch
6+
---
7+
8+
feat(spec): an action param's `helpText` takes an inline locale map, so an inline action can write its param hint per locale
9+
10+
Clause-②: yes (widening)
11+
Metadata-protocol: added
12+
13+
- **`@objectstack/spec`: `ActionParamSchema.helpText`** accepts an inline locale map (`{ en: 'Why the account is paused', 'zh-CN': '暂停该账户的原因' }`) beside the bare sentence and the `{ dialect: 'template', source }` envelope, the same three forms `description`, `confirmText`, `successMessage` and each `outcomeMessages` entry already take. It reaches every action that carries params: a registered action (`ActionSchema.params`) and a page button's inline `action` (`InlineActionSchema`). A registered action's hint is still translated through the bundle at `objects.<object>._actions.<action>.params.<param>.helpText`; the map is the form for an inline action, which no bundle reaches. Before, a page that wrote its dialog's title, line, option labels and toast as locale maps had to leave the hint out or show it in one language. Every value that parsed before parses to the same thing. A map key that is not a language tag is refused with the slot's own sentence.
14+
- **`@objectstack/lint`:** `os validate`, `compile` and the publish gate judge each entry of a `helpText` map as a sentence, named at `params[N].helpText.<locale>`, the way they judge a `description` map: a blank entry, a `${…}` or single-brace token, a hole over a root the dialog does not bind (`record` only), logic in a hole or an unknown formatter is an error. `os i18n extract` records the map as authored text (its locales count as covered, a locale it omits is reported) and scaffolds no bundle row for it.
15+
- **`@objectstack/runtime`:** the agent-facing tool schema (`summarizeActionParams`, read by the MCP action tools) reads a `helpText` map's source-language entry (`en`, then `default`, then any entry) instead of falling back to the bound field's description.
16+
- **`@object-ui/fields`:** `resolveActionParams` resolves a `helpText` map for the active language with the same order as `label`, so the param dialog draws the viewer's language. A map no longer falls through to the field's help line; an envelope with no `source` still does.
17+
18+
Callers that read `helpText` and may now see a map: the console's `resolveActionParams` (handled here), the runtime's `summarizeActionParams` (handled here), the lint copy door and the i18n walk (handled here), and the server-side `translateAction`, which overlays a bundle sentence when one exists and otherwise passes the authored value through unchanged, as it does for a `description` map.

‎content/docs/protocol/objectui/actions.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -516,6 +516,8 @@ params:
516516

517517
`ActionParam` fields: `name`, `field`, `objectOverride`, `label`, `type`, `required` (default `false`), `options`, `placeholder`, `helpText`, `defaultValue`, `defaultFromRow`, `visible` (CEL predicate — the dialog omits the param when false), `requiresFeature` (capability gate, lowered into `visible` — see [Capability gates](#capability-gates-requiresfeature)).
518518

519+
A param's `helpText` is the hint under its input. Write it as a sentence, translated at `objects.<object>._actions.<action>.params.<param>.helpText` (`globalActions.<action>.params.<param>.helpText` for an action with no `objectName`), or as an inline locale map (`helpText: { en: 'Why the account is paused', 'zh-CN': '暂停该账户的原因' }`), the same two forms `label` takes. A page button's inline `action` has no translation key, so the locale map is the way to translate its hint. Either form may hold `{{ record.* }}` holes.
520+
519521
### Naming the submit button: `submitText`
520522

521523
An action with `params` collects them in a dialog whose submit button says **Confirm**. `submitText` gives that button the action's own verb, so a send-email action can say **Send** and a log-call action **Log Call**. The dialog's other copy stays where it was: the title is the action's `label`, and the line under it is `description`.

‎content/docs/references/ui/action.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities
146146
| **required** | `boolean` | optional (default: `false`) | |
147147
| **options** | `{ label: string \| Record<string, string>; value: string; visibleWhen?: string \| object }[]` | optional | |
148148
| **placeholder** | `string` | optional | |
149-
| **helpText** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string` | optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
149+
| **helpText** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string \| Record<string, string>` | optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
150150
| **defaultValue** | `any` | optional | |
151151
| **multiple** | `boolean` | optional | Allow multiple values (array value shape); mirrors FieldSchema.multiple. |
152152
| **accept** | `string[]` | optional | Accepted upload types (MIME types / extensions) for file/image params. |
@@ -240,7 +240,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities
240240
| **required** | `boolean` | optional (default: `false`) | |
241241
| **options** | `{ label: string \| Record<string, string>; value: string; visibleWhen?: string \| object }[]` | optional | |
242242
| **placeholder** | `string` | optional | |
243-
| **helpText** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string` | optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
243+
| **helpText** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string \| Record<string, string>` | optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
244244
| **defaultValue** | `any` | optional | |
245245
| **multiple** | `boolean` | optional | Allow multiple values (array value shape); mirrors FieldSchema.multiple. |
246246
| **accept** | `string[]` | optional | Accepted upload types (MIME types / extensions) for file/image params. |
@@ -378,7 +378,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities
378378
| **required** | `boolean` | optional (default: `false`) | |
379379
| **options** | `{ label: string \| Record<string, string>; value: string; visibleWhen?: string \| object }[]` | optional | |
380380
| **placeholder** | `string` | optional | |
381-
| **helpText** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string` | optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
381+
| **helpText** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string \| Record<string, string>` | optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
382382
| **defaultValue** | `any` | optional | |
383383
| **multiple** | `boolean` | optional | Allow multiple values (array value shape); mirrors FieldSchema.multiple. |
384384
| **accept** | `string[]` | optional | Accepted upload types (MIME types / extensions) for file/image params. |

‎packages/cli/test/i18n-inline-locale-map-coverage.test.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -330,3 +330,65 @@ describe('coverage reads the map the way the renderer does', () => {
330330
expect(inlineLocaleText({ 'zh-CN': '成员' }, 'zh-TW')).toBe('成员');
331331
});
332332
});
333+
334+
// ─── An action param's `helpText` map (objectstack#28266) ─────────────
335+
336+
/**
337+
* A param's `helpText` took the inline locale map its siblings keep
338+
* (`description`, `outcomeMessages`, a param's `label`), so an inline action —
339+
* a page button's, which no bundle reaches — can write its dialog hint per
340+
* locale. The walker reads it as it reads a `description` map: authored, its
341+
* locales covered, and never scaffolded into a bundle row.
342+
*/
343+
const actionParamHelpMap = (): any => ({
344+
i18n: { defaultLocale: 'en', supportedLocales: LOCALES },
345+
objects: [{ name: 'member', label: 'Member', fields: { email: { label: 'Email' } } }],
346+
actions: [
347+
{
348+
name: 'pause_member',
349+
label: 'Pause',
350+
objectName: 'member',
351+
type: 'api',
352+
target: '/api/v1/pause',
353+
params: [
354+
{
355+
name: 'reason',
356+
label: 'Reason',
357+
type: 'text',
358+
helpText: { en: 'Why the member is paused', 'zh-CN': '暂停该成员的原因', 'ja-JP': 'メンバーを一時停止する理由' },
359+
},
360+
],
361+
},
362+
],
363+
});
364+
365+
describe("an action param's helpText map is authored text too (#28266)", () => {
366+
const key = (config: any) => walkedKeys(config).find((k) => k.endsWith('.params.reason.helpText'));
367+
368+
it('records the map at the param key and counts every locale it holds as covered', () => {
369+
const at = key(actionParamHelpMap());
370+
expect(at).toBeDefined();
371+
const entry = collectExpectedEntries(actionParamHelpMap()).find((e) => e.path.join('.') === at);
372+
expect(entry!.inlineLocales).toEqual({
373+
en: 'Why the member is paused',
374+
'zh-CN': '暂停该成员的原因',
375+
'ja-JP': 'メンバーを一時停止する理由',
376+
});
377+
expect(gaps(computeI18nCoverage(actionParamHelpMap(), { locales: LOCALES }), at!)).toEqual([]);
378+
});
379+
380+
it('a partial map still reports the locale it omits', () => {
381+
const partial = actionParamHelpMap();
382+
delete partial.actions[0].params[0].helpText['ja-JP'];
383+
const at = key(partial)!;
384+
expect(gaps(computeI18nCoverage(partial, { locales: LOCALES }), at)).toEqual(['ja-JP']);
385+
});
386+
387+
it('scaffolds no bundle row for the map, in any locale', () => {
388+
const result = extractTranslations(actionParamHelpMap(), { defaultLocale: 'en', locales: LOCALES });
389+
for (const locale of LOCALES) {
390+
expect(JSON.stringify(result.bundles[locale] ?? {}), locale).not.toContain('暂停该成员的原因');
391+
expect(JSON.stringify(result.bundles[locale] ?? {}), locale).not.toContain('Why the member is paused');
392+
}
393+
});
394+
});

‎packages/lint/src/i18n-walk.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -644,10 +644,10 @@ function pushDerived(
644644
}
645645

646646
/**
647-
* [#24814, #27948] An action's `confirmText` / `successMessage` /
648-
* `description` / `outcomeMessages` entry is a `template` slot that also takes
649-
* an inline locale map, and a param's `helpText` one without it: a bare
650-
* string, the parsed
647+
* [#24814, #27948, #28266] An action's `confirmText` / `successMessage` /
648+
* `description` / `outcomeMessages` entry and a param's `helpText` are
649+
* `template` slots that also take an inline locale map: a bare string, the
650+
* parsed
651651
* `{ dialect: 'template', source }` envelope, or the map. The envelope and the
652652
* string are the same authored sentence, so the envelope is read through the
653653
* template judge's one reader and seeded like the string; anything else (the

‎packages/lint/src/validate-action-copy-templates.test.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -303,6 +303,33 @@ describe('validateStackExpressions — description, params[].helpText and outcom
303303
expect(issues[0]!.message).toContain('is blank');
304304
});
305305

306+
// #28266: a param's `helpText` takes the inline locale map its siblings keep,
307+
// so each entry is a sentence the doors judge at `.<locale>` — on a
308+
// registered action and on a page button's inline action alike.
309+
it('passes a helpText locale map and judges each entry at `.<locale>`', () => {
310+
const map = { en: 'Why pause {{ record.name }}?', 'zh-CN': '为什么暂停 {{ record.name }}?' };
311+
expect(newSlotIssues({ objects, actions: [invite(withParam(map))] })).toEqual([]);
312+
313+
const registered = newSlotIssues({
314+
objects,
315+
actions: [invite(withParam({ en: 'Why pause {{ record.name }}?', 'zh-CN': '为什么暂停 ${record.name}?', 'ja-JP': ' ' }))],
316+
});
317+
expect(registered.map((i) => [i.where, i.severity])).toEqual([
318+
["stack · action 'invite' params[0].helpText.zh-CN", 'error'],
319+
["stack · action 'invite' params[0].helpText.ja-JP", 'error'],
320+
]);
321+
expect(registered[0]!.message).toContain("An action param's `helpText`");
322+
expect(registered[1]!.message).toContain('is blank');
323+
324+
const page = pageWith([{
325+
type: 'element:button',
326+
properties: { action: { type: 'script', target: 'run', params: [{ name: 'reason', type: 'text', helpText: { en: 'Why', 'zh-CN': '{{ result.email }}' } }] } },
327+
}]);
328+
const pageIssues = runStackExpressionPasses({ objects, pages: [page] }, { runtimeWriteType: 'page' })
329+
.filter((i) => /helpText/.test(i.where));
330+
expect(pageIssues.map((i) => i.where)).toEqual([expect.stringContaining('· action params[0].helpText.zh-CN')]);
331+
});
332+
306333
it('judges an inline `properties.action` param helpText; an object\'s own action on an object write', () => {
307334
const page = pageWith([{
308335
type: 'element:button',

‎packages/lint/src/validate-action-copy-templates.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,15 @@
1010
* `confirmText` and `successMessage`, each a bare string, the parsed
1111
* envelope, or an inline locale map whose every value is such a sentence —
1212
* and, since #27948 (ruling A, step 2), `description`, each
13-
* `outcomeMessages` entry (both with the locale map) and each
14-
* `params[].helpText` (without it);
13+
* `outcomeMessages` entry and each `params[].helpText` (all three with the
14+
* locale map; `helpText` took it in #28266);
1515
* - a page action row — `action:button` / `action:icon` `properties`, and
1616
* each `properties.actions[]` member of an `action:group` / `action:menu` —
1717
* all three keys;
1818
* - a page component's inline `properties.action` (`InlineActionSchema`, the
1919
* pick of `ActionSchema` an `element:button` carries): `confirmText`,
20-
* `successMessage`, `description` (each with the locale map) and each
21-
* `params[].helpText`.
20+
* `successMessage`, `description` and each `params[].helpText`, each with
21+
* the locale map.
2222
*
2323
* The same two steps the bulk `confirmText` pass takes, through the same
2424
* judge: `closedScopeTemplateRefusal` names a `${…}` or single-brace token
@@ -176,12 +176,12 @@ function judgeAction(
176176
localeMap: boolean,
177177
): void {
178178
for (const key of keys) {
179-
// A param's `helpText` was a plain string, never a locale map (#27948).
180-
const takesMap = localeMap && key !== 'helpText';
181179
const slot = SLOT_NAME[key];
182180
const roots = rootsOf(key, action);
183181
for (const { path, value } of valuesOf(action, key)) {
184-
for (const { at, text } of sentencesOf(value, takesMap)) {
182+
// A param's `helpText` takes the locale map too (#28266): each entry is
183+
// judged at `.<locale>`, like a `description` entry.
184+
for (const { at, text } of sentencesOf(value, localeMap)) {
185185
const located = `${where} ${path}${at}`;
186186
const refuse = (message: string, quoted: string): void => {
187187
issues.push({ where: located, message, source: quoted, severity: 'error' });

0 commit comments

Comments
 (0)