@object-ui/i18n 17.7.0 → 18.0.0

package/dist/useObjectLabel.d.ts

@@ -11,6 +11,7 @@
  * | What               | Auto-generated key                              | Fallback              |
  * |--------------------|-------------------------------------------------|-----------------------|
  * | Object label       | {ns}.objects.{objectName}.label                  | objectDef.label       |
+ * | Object plural      | {ns}.objects.{objectName}.pluralLabel            | objectDef.pluralLabel, then the object label |
  * | Object description | {ns}.objects.{objectName}.description             | objectDef.description |
  * | Field label        | {ns}.fields.{objectName}.{fieldName}              | field.label           |
  *
@@ -39,6 +40,32 @@ export declare function useObjectLabel(): {
         name: string;
         label: string;
     }) => string;
+    /**
+     * Resolve the object's PLURAL label — what a list of its records is called:
+     * an object list page's title and the breadcrumb segment that links to that
+     * list (objectui#11696). Record-scoped surfaces (the record page, a record
+     * drawer, "New …") keep {@link objectLabel}.
+     *
+     * Order: the translated plural (`{ns}.objects.{objectName}.pluralLabel`),
+     * else the declared `objectDef.pluralLabel`, else the singular as
+     * `objectLabel` resolves it — `pluralLabel` is optional in the spec, and an
+     * object that declares none is called by its label everywhere.
+     *
+     * The first two rungs are the client half of `translateObject` in
+     * `@objectstack/spec` (`system/i18n-resolver`), which serves `pluralLabel`
+     * as the catalog entry, else the authored value. There is deliberately NO
+     * rung that prefers a translated SINGULAR over a declared plural the bundle
+     * leaves untranslated: the server has none either, so every consumer of
+     * `/meta` shows the authored plural in that case, and this client showing
+     * something else would be a second dialect (see `viewSuffixes`). The gap is
+     * the bundle's — `os i18n extract` writes `pluralLabel` wherever the object
+     * declares one — and is fixed there.
+     */
+    objectPluralLabel: (objectDef: {
+        name: string;
+        label: string;
+        pluralLabel?: string;
+    }) => string;
     /**
      * Resolve translated object description, falling back to objectDef.description.
      */
@@ -147,31 +174,13 @@ export declare function useObjectLabel(): {
      * Resolve translated widget description within a dashboard.
      * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.description`.
      * Returns undefined when neither metadata nor translation provides one.
-     */
-    widgetDescription: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
-    /**
-     * Resolve a translated metric-widget SUB-CAPTION within a dashboard.
-     * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.subCaption`.
-     * Returns undefined when neither metadata nor translation provides one.
-     *
-     * Deliberately its OWN key, not a second reader of `widgets.{id}.description`.
-     * The KPI card renders two authored strings from two different fields — the
-     * shared card header's `widget.description`, and the sub-caption under the
-     * value, which is authored as `widget.options.description` — and the
-     * objectstack#5428 item-4 ruling (2026-08-06) settled that they get two
-     * keys, not one: 「两个作者字段两个 key」. Collapsing them would make one
-     * translation entry silently retarget the other field on any widget type
-     * that renders both at once (`kpi`, `gauge`, `bullet` — every metric-family
-     * type except the self-contained `metric`).
      *
-     * `subCaption` is the member objectstack#8056 added to the widget
-     * translation node for exactly this, shipped in `@objectstack/spec@17.0.0`.
-     * The server-side resolver reads the SAME key and overlays it onto
-     * `options.description` (`translateDashboard`), so a document served
-     * through `/meta` and a document translated here land on the same string —
-     * this is the client half of one convention, not a second dialect.
+     * This is a widget's ONE translated description. The sibling sub-caption
+     * key, `widgets.{widgetId}.subCaption`, is retired with its resolver
+     * (objectui#11389, ruling C): `@objectstack/spec` 17.7.0 refuses it by
+     * name in a translation bundle, and nothing here reads it.
      */
-    widgetSubCaption: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
+    widgetDescription: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated page label, falling back to pageDef.label.
      * Convention: `{ns}.pages.{pageName}.label`.
@@ -218,32 +227,33 @@ export declare function useObjectLabel(): {
     sectionLabel: (objectName: string, sectionName: string, fallback: string) => string;
     /**
      * Resolve translated action label.
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.label`,
-     * falling back to `{ns}.globalActions.{actionName}.label` — both when
-     * objectName is omitted AND when the object-scoped key misses (so a
-     * globalAction surfaced on a record-detail action bar still resolves;
-     * objectui#3372).
+     * `objectName` is the action's KEY object (its declared `objectName`, else
+     * the host that embeds it). Convention:
+     * `{ns}.objects.{objectName}._actions.{actionName}.label`; with no key
+     * object, `{ns}.globalActions.{actionName}.label`. Never both: a bound
+     * action does not read `globalActions` (objectui#11439, see
+     * `actionSuffixes`). Every action resolver below follows the same rule.
      */
     actionLabel: (objectName: string | undefined, actionName: string, fallback: string) => string;
     /**
      * Resolve translated action confirmation prompt.
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.confirmText`,
-     * falling back to `{ns}.globalActions.{actionName}.confirmText`.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.confirmText`;
+     * with no key object, `{ns}.globalActions.{actionName}.confirmText`.
      * Returns undefined when no translation and no fallback exist.
      */
     actionConfirm: (objectName: string | undefined, actionName: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated action success message.
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.successMessage`,
-     * falling back to `{ns}.globalActions.{actionName}.successMessage`.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.successMessage`;
+     * with no key object, `{ns}.globalActions.{actionName}.successMessage`.
      */
     actionSuccess: (objectName: string | undefined, actionName: string, fallback?: string) => string | undefined;
     /**
      * Resolve the translated success copy for ONE handler outcome — an entry of
      * the action's `outcomeMessages` (`@objectstack/spec` 17.6.0, objectui#11344).
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.outcomeMessages.{outcome}`,
-     * falling back to `{ns}.globalActions.{actionName}.outcomeMessages.{outcome}`
-     * — the address the spec's translation bundle declares for the key.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.outcomeMessages.{outcome}`;
+     * with no key object, `{ns}.globalActions.{actionName}.outcomeMessages.{outcome}`
+     * — the addresses the spec's translation bundle declares for the key.
      * Returns undefined when no translation and no fallback exist.
      *
      * Like `actionSuccess`, the answer is a TEMPLATE: a `${result.*}` token in a
@@ -255,18 +265,17 @@ export declare function useObjectLabel(): {
     /**
      * Resolve translated action description (the explanatory line shown in the
      * action's param dialog / sheet / drawer header).
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.description`.
-     * Falls back to `{ns}.globalActions.{actionName}.description`, then the
-     * metadata's literal string; undefined when nothing resolves.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.description`;
+     * with no key object, `{ns}.globalActions.{actionName}.description`. Falls
+     * back to the metadata's literal string; undefined when nothing resolves.
      */
     actionDescription: (objectName: string | undefined, actionName: string | undefined, fallback?: string) => string | undefined;
     /**
      * Resolve a translated copy of an action's post-success RESULT DIALOG
      * (`title` / `description` / `acknowledge` + per-field labels).
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.resultDialog.*`,
-     * falling back to `{ns}.globalActions.{actionName}.resultDialog.*` (when
-     * objectName is omitted OR the object-scoped key misses), then to the
-     * metadata's literal strings.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.resultDialog.*`;
+     * with no key object, `{ns}.globalActions.{actionName}.resultDialog.*`.
+     * Falls back to the metadata's literal strings.
      *
      * The `fields` translation node is keyed by the LITERAL result-field path
      * from the action metadata (may contain dots, e.g. `"user.email"`), so it
@@ -285,14 +294,16 @@ export declare function useObjectLabel(): {
     }>(objectName: string | undefined, actionName: string | undefined, spec: T | undefined) => T | undefined;
     /**
      * Resolve translated action-PARAMETER text (label / placeholder / helpText).
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.{attr}`.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.{attr}`;
+     * with no key object, `{ns}.globalActions.{actionName}.params.{paramName}.{attr}`.
      * Falls back to the provided value (the metadata's literal string) when no
      * translation exists, so untranslated params keep rendering as authored.
      */
     actionParamText: (objectName: string | undefined, actionName: string | undefined, paramName: string, attr: "label" | "placeholder" | "helpText", fallback?: string) => string | undefined;
     /**
      * Resolve a translated action-parameter SELECT OPTION label.
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.options.{optionValue}`.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.options.{optionValue}`;
+     * with no key object, the same path under `{ns}.globalActions.{actionName}`.
      * Falls back to the provided (English metadata) label when untranslated.
      */
     actionParamOptionLabel: (objectName: string | undefined, actionName: string | undefined, paramName: string, optionValue: string, fallback: string) => string;
@@ -310,6 +321,32 @@ export declare function useSafeFieldLabel(): {
         name: string;
         label: string;
     }) => string;
+    /**
+     * Resolve the object's PLURAL label — what a list of its records is called:
+     * an object list page's title and the breadcrumb segment that links to that
+     * list (objectui#11696). Record-scoped surfaces (the record page, a record
+     * drawer, "New …") keep {@link objectLabel}.
+     *
+     * Order: the translated plural (`{ns}.objects.{objectName}.pluralLabel`),
+     * else the declared `objectDef.pluralLabel`, else the singular as
+     * `objectLabel` resolves it — `pluralLabel` is optional in the spec, and an
+     * object that declares none is called by its label everywhere.
+     *
+     * The first two rungs are the client half of `translateObject` in
+     * `@objectstack/spec` (`system/i18n-resolver`), which serves `pluralLabel`
+     * as the catalog entry, else the authored value. There is deliberately NO
+     * rung that prefers a translated SINGULAR over a declared plural the bundle
+     * leaves untranslated: the server has none either, so every consumer of
+     * `/meta` shows the authored plural in that case, and this client showing
+     * something else would be a second dialect (see `viewSuffixes`). The gap is
+     * the bundle's — `os i18n extract` writes `pluralLabel` wherever the object
+     * declares one — and is fixed there.
+     */
+    objectPluralLabel: (objectDef: {
+        name: string;
+        label: string;
+        pluralLabel?: string;
+    }) => string;
     /**
      * Resolve translated object description, falling back to objectDef.description.
      */
@@ -418,31 +455,13 @@ export declare function useSafeFieldLabel(): {
      * Resolve translated widget description within a dashboard.
      * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.description`.
      * Returns undefined when neither metadata nor translation provides one.
-     */
-    widgetDescription: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
-    /**
-     * Resolve a translated metric-widget SUB-CAPTION within a dashboard.
-     * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.subCaption`.
-     * Returns undefined when neither metadata nor translation provides one.
-     *
-     * Deliberately its OWN key, not a second reader of `widgets.{id}.description`.
-     * The KPI card renders two authored strings from two different fields — the
-     * shared card header's `widget.description`, and the sub-caption under the
-     * value, which is authored as `widget.options.description` — and the
-     * objectstack#5428 item-4 ruling (2026-08-06) settled that they get two
-     * keys, not one: 「两个作者字段两个 key」. Collapsing them would make one
-     * translation entry silently retarget the other field on any widget type
-     * that renders both at once (`kpi`, `gauge`, `bullet` — every metric-family
-     * type except the self-contained `metric`).
      *
-     * `subCaption` is the member objectstack#8056 added to the widget
-     * translation node for exactly this, shipped in `@objectstack/spec@17.0.0`.
-     * The server-side resolver reads the SAME key and overlays it onto
-     * `options.description` (`translateDashboard`), so a document served
-     * through `/meta` and a document translated here land on the same string —
-     * this is the client half of one convention, not a second dialect.
+     * This is a widget's ONE translated description. The sibling sub-caption
+     * key, `widgets.{widgetId}.subCaption`, is retired with its resolver
+     * (objectui#11389, ruling C): `@objectstack/spec` 17.7.0 refuses it by
+     * name in a translation bundle, and nothing here reads it.
      */
-    widgetSubCaption: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
+    widgetDescription: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated page label, falling back to pageDef.label.
      * Convention: `{ns}.pages.{pageName}.label`.
@@ -489,32 +508,33 @@ export declare function useSafeFieldLabel(): {
     sectionLabel: (objectName: string, sectionName: string, fallback: string) => string;
     /**
      * Resolve translated action label.
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.label`,
-     * falling back to `{ns}.globalActions.{actionName}.label` — both when
-     * objectName is omitted AND when the object-scoped key misses (so a
-     * globalAction surfaced on a record-detail action bar still resolves;
-     * objectui#3372).
+     * `objectName` is the action's KEY object (its declared `objectName`, else
+     * the host that embeds it). Convention:
+     * `{ns}.objects.{objectName}._actions.{actionName}.label`; with no key
+     * object, `{ns}.globalActions.{actionName}.label`. Never both: a bound
+     * action does not read `globalActions` (objectui#11439, see
+     * `actionSuffixes`). Every action resolver below follows the same rule.
      */
     actionLabel: (objectName: string | undefined, actionName: string, fallback: string) => string;
     /**
      * Resolve translated action confirmation prompt.
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.confirmText`,
-     * falling back to `{ns}.globalActions.{actionName}.confirmText`.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.confirmText`;
+     * with no key object, `{ns}.globalActions.{actionName}.confirmText`.
      * Returns undefined when no translation and no fallback exist.
      */
     actionConfirm: (objectName: string | undefined, actionName: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated action success message.
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.successMessage`,
-     * falling back to `{ns}.globalActions.{actionName}.successMessage`.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.successMessage`;
+     * with no key object, `{ns}.globalActions.{actionName}.successMessage`.
      */
     actionSuccess: (objectName: string | undefined, actionName: string, fallback?: string) => string | undefined;
     /**
      * Resolve the translated success copy for ONE handler outcome — an entry of
      * the action's `outcomeMessages` (`@objectstack/spec` 17.6.0, objectui#11344).
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.outcomeMessages.{outcome}`,
-     * falling back to `{ns}.globalActions.{actionName}.outcomeMessages.{outcome}`
-     * — the address the spec's translation bundle declares for the key.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.outcomeMessages.{outcome}`;
+     * with no key object, `{ns}.globalActions.{actionName}.outcomeMessages.{outcome}`
+     * — the addresses the spec's translation bundle declares for the key.
      * Returns undefined when no translation and no fallback exist.
      *
      * Like `actionSuccess`, the answer is a TEMPLATE: a `${result.*}` token in a
@@ -526,18 +546,17 @@ export declare function useSafeFieldLabel(): {
     /**
      * Resolve translated action description (the explanatory line shown in the
      * action's param dialog / sheet / drawer header).
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.description`.
-     * Falls back to `{ns}.globalActions.{actionName}.description`, then the
-     * metadata's literal string; undefined when nothing resolves.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.description`;
+     * with no key object, `{ns}.globalActions.{actionName}.description`. Falls
+     * back to the metadata's literal string; undefined when nothing resolves.
      */
     actionDescription: (objectName: string | undefined, actionName: string | undefined, fallback?: string) => string | undefined;
     /**
      * Resolve a translated copy of an action's post-success RESULT DIALOG
      * (`title` / `description` / `acknowledge` + per-field labels).
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.resultDialog.*`,
-     * falling back to `{ns}.globalActions.{actionName}.resultDialog.*` (when
-     * objectName is omitted OR the object-scoped key misses), then to the
-     * metadata's literal strings.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.resultDialog.*`;
+     * with no key object, `{ns}.globalActions.{actionName}.resultDialog.*`.
+     * Falls back to the metadata's literal strings.
      *
      * The `fields` translation node is keyed by the LITERAL result-field path
      * from the action metadata (may contain dots, e.g. `"user.email"`), so it
@@ -556,14 +575,16 @@ export declare function useSafeFieldLabel(): {
     }>(objectName: string | undefined, actionName: string | undefined, spec: T | undefined) => T | undefined;
     /**
      * Resolve translated action-PARAMETER text (label / placeholder / helpText).
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.{attr}`.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.{attr}`;
+     * with no key object, `{ns}.globalActions.{actionName}.params.{paramName}.{attr}`.
      * Falls back to the provided value (the metadata's literal string) when no
      * translation exists, so untranslated params keep rendering as authored.
      */
     actionParamText: (objectName: string | undefined, actionName: string | undefined, paramName: string, attr: "label" | "placeholder" | "helpText", fallback?: string) => string | undefined;
     /**
      * Resolve a translated action-parameter SELECT OPTION label.
-     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.options.{optionValue}`.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.options.{optionValue}`;
+     * with no key object, the same path under `{ns}.globalActions.{actionName}`.
      * Falls back to the provided (English metadata) label when untranslated.
      */
     actionParamOptionLabel: (objectName: string | undefined, actionName: string | undefined, paramName: string, optionValue: string, fallback: string) => string;

package/dist/useObjectLabel.js

@@ -11,6 +11,7 @@
  * | What               | Auto-generated key                              | Fallback              |
  * |--------------------|-------------------------------------------------|-----------------------|
  * | Object label       | {ns}.objects.{objectName}.label                  | objectDef.label       |
+ * | Object plural      | {ns}.objects.{objectName}.pluralLabel            | objectDef.pluralLabel, then the object label |
  * | Object description | {ns}.objects.{objectName}.description             | objectDef.description |
  * | Field label        | {ns}.fields.{objectName}.{fieldName}              | field.label           |
  *
@@ -108,9 +109,10 @@ export function useObjectLabel() {
          * include crm.objects.* or crm.apps.*.
          *
          * `globalActions` is included so an app bundle whose only translated scope
-         * is global actions (no object/field entries) is still discovered — its
-         * `globalActions.<action>.*` overlays would otherwise be unreachable
-         * (objectui#3372).
+         * is global actions (no object/field entries) is still discovered — the
+         * `globalActions.<action>.*` copy of its object-less actions would otherwise
+         * be unreachable (objectui#3372; object-less only since objectui#11439, see
+         * `actionSuffixes`).
          */
         const getAppNamespaces = () => {
             if (!hasUsableI18nInstance(i18n))
@@ -168,28 +170,35 @@ export function useObjectLabel() {
         };
         /**
          * Build suffix candidates for an action-scoped key, mirroring the canonical
-         * `@objectstack/spec` resolver (`lookupActionField` in `system/i18n-resolver`).
+         * `@objectstack/spec` resolver (`actionTranslationNode` behind
+         * `lookupActionField`, in `system/i18n-resolver`): ONE node per action, chosen
+         * by its key object.
          *
-         * When the action is object-scoped, the object key
-         * (`objects.<obj>._actions.<action>.<tail>`) wins, but the global key
-         * (`globalActions.<action>.<tail>`) is appended as a fallback so a
-         * **globalAction surfaced on an object's action bar** still picks up its
-         * `globalActions.<action>.*` overlay when no object-scoped translation
-         * exists (objectui#3372). Without this fallback, a globalAction rendered on
-         * a record-detail action bar — where the caller passes `objectDef.name` for
-         * every action — misses `objects.<obj>._actions.<action>.label` and leaks the
-         * English metadata literal.
+         * `objectName` is the action's KEY object — the object the action belongs
+         * to: its declared `objectName`, else the host object that embeds it, which
+         * is what the spec's `translateObject` stamps on an embedded action. Callers
+         * pass that object (`useActionTextLocalizer` derives it from the action).
          *
-         * Object-less actions (`objectName` omitted) resolve straight to the global
-         * namespace, as before. Object precedence is preserved: the global key is
-         * only consulted after every object-scoped candidate misses.
+         * - A key object reads `objects.<obj>._actions.<action>.<tail>` and nothing
+         *   else.
+         * - No key object reads `globalActions.<action>.<tail>` and nothing else.
+         *
+         * There is deliberately NO object-then-global chain. objectui#3372 added one
+         * so `globalActions` copy reached actions drawn on an object's bar; the
+         * spec's `TranslationDataSchema.globalActions` is for actions "not bound to a
+         * specific object via `objectName`", `@objectstack/spec` 17.7.0 never reads it
+         * for a bound action, and objectui#11439 (triage's amended ruling) retired the
+         * chain so this client and the server resolve one bundle entry the same way.
+         * A bound action's copy filed under `globalActions` now misses on every
+         * surface alike and the authored text shows — the misfiling is what
+         * `os validate` already refuses, and it is fixed in the bundle, not here.
+         *
+         * The two object-name candidates (`objects.<ns__obj>` then `objects.<obj>`)
+         * are a separate axis and stay — see `stripNamespace`.
          */
-        const actionSuffixes = (objectName, actionName, tail) => {
-            const globalSuffix = `globalActions.${actionName}.${tail}`;
-            return objectName
-                ? [...objectSuffixes(objectName, `_actions.${actionName}.${tail}`), globalSuffix]
-                : [globalSuffix];
-        };
+        const actionSuffixes = (objectName, actionName, tail) => objectName
+            ? objectSuffixes(objectName, `_actions.${actionName}.${tail}`)
+            : [`globalActions.${actionName}.${tail}`];
         const fieldSuffixes = (objectName, fieldName) => {
             const base = stripNamespace(objectName);
             return base !== objectName
@@ -268,11 +277,37 @@ export function useObjectLabel() {
             const bareViewName = matchedPrefix ? viewName.slice(matchedPrefix.length) : viewName;
             return objectSuffixes(objectName, `_views.${bareViewName}.${tail}`);
         };
+        /** The singular object label; `objectPluralLabel` falls back to it. */
+        const objectLabel = (objectDef) => resolve(objectSuffixes(objectDef.name, 'label'), objectDef.label);
         return {
             /**
              * Resolve translated object label, falling back to objectDef.label.
              */
-            objectLabel: (objectDef) => resolve(objectSuffixes(objectDef.name, 'label'), objectDef.label),
+            objectLabel,
+            /**
+             * Resolve the object's PLURAL label — what a list of its records is called:
+             * an object list page's title and the breadcrumb segment that links to that
+             * list (objectui#11696). Record-scoped surfaces (the record page, a record
+             * drawer, "New …") keep {@link objectLabel}.
+             *
+             * Order: the translated plural (`{ns}.objects.{objectName}.pluralLabel`),
+             * else the declared `objectDef.pluralLabel`, else the singular as
+             * `objectLabel` resolves it — `pluralLabel` is optional in the spec, and an
+             * object that declares none is called by its label everywhere.
+             *
+             * The first two rungs are the client half of `translateObject` in
+             * `@objectstack/spec` (`system/i18n-resolver`), which serves `pluralLabel`
+             * as the catalog entry, else the authored value. There is deliberately NO
+             * rung that prefers a translated SINGULAR over a declared plural the bundle
+             * leaves untranslated: the server has none either, so every consumer of
+             * `/meta` shows the authored plural in that case, and this client showing
+             * something else would be a second dialect (see `viewSuffixes`). The gap is
+             * the bundle's — `os i18n extract` writes `pluralLabel` wherever the object
+             * declares one — and is fixed there.
+             */
+            objectPluralLabel: (objectDef) => resolve(objectSuffixes(objectDef.name, 'pluralLabel'), '')
+                || objectDef.pluralLabel
+                || objectLabel(objectDef),
             /**
              * Resolve translated object description, falling back to objectDef.description.
              */
@@ -373,39 +408,17 @@ export function useObjectLabel() {
              * Resolve translated widget description within a dashboard.
              * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.description`.
              * Returns undefined when neither metadata nor translation provides one.
+             *
+             * This is a widget's ONE translated description. The sibling sub-caption
+             * key, `widgets.{widgetId}.subCaption`, is retired with its resolver
+             * (objectui#11389, ruling C): `@objectstack/spec` 17.7.0 refuses it by
+             * name in a translation bundle, and nothing here reads it.
              */
             widgetDescription: (dashboardName, widgetId, fallback) => {
                 const fb = fallback ?? '';
                 const resolved = resolve(dashboardSuffixes(dashboardName, `widgets.${widgetId}.description`), fb);
                 return resolved || undefined;
             },
-            /**
-             * Resolve a translated metric-widget SUB-CAPTION within a dashboard.
-             * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.subCaption`.
-             * Returns undefined when neither metadata nor translation provides one.
-             *
-             * Deliberately its OWN key, not a second reader of `widgets.{id}.description`.
-             * The KPI card renders two authored strings from two different fields — the
-             * shared card header's `widget.description`, and the sub-caption under the
-             * value, which is authored as `widget.options.description` — and the
-             * objectstack#5428 item-4 ruling (2026-08-06) settled that they get two
-             * keys, not one: 「两个作者字段两个 key」. Collapsing them would make one
-             * translation entry silently retarget the other field on any widget type
-             * that renders both at once (`kpi`, `gauge`, `bullet` — every metric-family
-             * type except the self-contained `metric`).
-             *
-             * `subCaption` is the member objectstack#8056 added to the widget
-             * translation node for exactly this, shipped in `@objectstack/spec@17.0.0`.
-             * The server-side resolver reads the SAME key and overlays it onto
-             * `options.description` (`translateDashboard`), so a document served
-             * through `/meta` and a document translated here land on the same string —
-             * this is the client half of one convention, not a second dialect.
-             */
-            widgetSubCaption: (dashboardName, widgetId, fallback) => {
-                const fb = fallback ?? '';
-                const resolved = resolve(dashboardSuffixes(dashboardName, `widgets.${widgetId}.subCaption`), fb);
-                return resolved || undefined;
-            },
             /**
              * Resolve translated page label, falling back to pageDef.label.
              * Convention: `{ns}.pages.{pageName}.label`.
@@ -469,17 +482,18 @@ export function useObjectLabel() {
             sectionLabel: (objectName, sectionName, fallback) => resolve(objectSuffixes(objectName, `_sections.${sectionName}.label`), fallback),
             /**
              * Resolve translated action label.
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.label`,
-             * falling back to `{ns}.globalActions.{actionName}.label` — both when
-             * objectName is omitted AND when the object-scoped key misses (so a
-             * globalAction surfaced on a record-detail action bar still resolves;
-             * objectui#3372).
+             * `objectName` is the action's KEY object (its declared `objectName`, else
+             * the host that embeds it). Convention:
+             * `{ns}.objects.{objectName}._actions.{actionName}.label`; with no key
+             * object, `{ns}.globalActions.{actionName}.label`. Never both: a bound
+             * action does not read `globalActions` (objectui#11439, see
+             * `actionSuffixes`). Every action resolver below follows the same rule.
              */
             actionLabel: (objectName, actionName, fallback) => resolve(actionSuffixes(objectName, actionName, 'label'), fallback),
             /**
              * Resolve translated action confirmation prompt.
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.confirmText`,
-             * falling back to `{ns}.globalActions.{actionName}.confirmText`.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.confirmText`;
+             * with no key object, `{ns}.globalActions.{actionName}.confirmText`.
              * Returns undefined when no translation and no fallback exist.
              */
             actionConfirm: (objectName, actionName, fallback) => {
@@ -489,8 +503,8 @@ export function useObjectLabel() {
             },
             /**
              * Resolve translated action success message.
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.successMessage`,
-             * falling back to `{ns}.globalActions.{actionName}.successMessage`.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.successMessage`;
+             * with no key object, `{ns}.globalActions.{actionName}.successMessage`.
              */
             actionSuccess: (objectName, actionName, fallback) => {
                 const fb = fallback ?? '';
@@ -500,9 +514,9 @@ export function useObjectLabel() {
             /**
              * Resolve the translated success copy for ONE handler outcome — an entry of
              * the action's `outcomeMessages` (`@objectstack/spec` 17.6.0, objectui#11344).
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.outcomeMessages.{outcome}`,
-             * falling back to `{ns}.globalActions.{actionName}.outcomeMessages.{outcome}`
-             * — the address the spec's translation bundle declares for the key.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.outcomeMessages.{outcome}`;
+             * with no key object, `{ns}.globalActions.{actionName}.outcomeMessages.{outcome}`
+             * — the addresses the spec's translation bundle declares for the key.
              * Returns undefined when no translation and no fallback exist.
              *
              * Like `actionSuccess`, the answer is a TEMPLATE: a `${result.*}` token in a
@@ -518,9 +532,9 @@ export function useObjectLabel() {
             /**
              * Resolve translated action description (the explanatory line shown in the
              * action's param dialog / sheet / drawer header).
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.description`.
-             * Falls back to `{ns}.globalActions.{actionName}.description`, then the
-             * metadata's literal string; undefined when nothing resolves.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.description`;
+             * with no key object, `{ns}.globalActions.{actionName}.description`. Falls
+             * back to the metadata's literal string; undefined when nothing resolves.
              */
             actionDescription: (objectName, actionName, fallback) => {
                 const fb = fallback ?? '';
@@ -532,10 +546,9 @@ export function useObjectLabel() {
             /**
              * Resolve a translated copy of an action's post-success RESULT DIALOG
              * (`title` / `description` / `acknowledge` + per-field labels).
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.resultDialog.*`,
-             * falling back to `{ns}.globalActions.{actionName}.resultDialog.*` (when
-             * objectName is omitted OR the object-scoped key misses), then to the
-             * metadata's literal strings.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.resultDialog.*`;
+             * with no key object, `{ns}.globalActions.{actionName}.resultDialog.*`.
+             * Falls back to the metadata's literal strings.
              *
              * The `fields` translation node is keyed by the LITERAL result-field path
              * from the action metadata (may contain dots, e.g. `"user.email"`), so it
@@ -588,7 +601,8 @@ export function useObjectLabel() {
             },
             /**
              * Resolve translated action-PARAMETER text (label / placeholder / helpText).
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.{attr}`.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.{attr}`;
+             * with no key object, `{ns}.globalActions.{actionName}.params.{paramName}.{attr}`.
              * Falls back to the provided value (the metadata's literal string) when no
              * translation exists, so untranslated params keep rendering as authored.
              */
@@ -601,7 +615,8 @@ export function useObjectLabel() {
             },
             /**
              * Resolve a translated action-parameter SELECT OPTION label.
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.options.{optionValue}`.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.options.{optionValue}`;
+             * with no key object, the same path under `{ns}.globalActions.{actionName}`.
              * Falls back to the provided (English metadata) label when untranslated.
              */
             actionParamOptionLabel: (objectName, actionName, paramName, optionValue, fallback) => {