@object-ui/i18n 17.6.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.
      */
@@ -100,15 +127,17 @@ export declare function useObjectLabel(): {
      * reaches this client — so nav labels arrive already localized. One
      * owner, not two. To translate a sidebar group, translate it there.
      *
-     * History (objectui#5197): until then this docstring promised
+     * History (`9c60144b5`): until then this docstring promised
      * `"Sales" → "销售"` for sidebar groups, and `NavigationRenderer`
      * accepted `resolveGroupLabel`/`resolveItemLabel` to wire it up. Those
      * props could never fire — the renderer's `isCustomized` guard compared a
      * node's authored label against its own `id` (`Workspace` vs
      * `grp_workspace`), which never match, so the guard was true for every
-     * real entry. The props are gone; the promise was false, not merely
-     * unused. This helper is kept as a plain key reader for a consumer that
-     * renders navigation itself — it has no first-party caller.
+     * real entry. The props are gone, and so is the guard itself
+     * (objectui#11201: the renderer no longer matches a label's text against
+     * any name); the promise was false, not merely unused. This helper is kept
+     * as a plain key reader for a consumer that renders navigation itself — it
+     * has no first-party caller.
      */
     navGroupLabel: (appName: string, groupId: string, fallback: string) => string;
     /**
@@ -145,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`.
@@ -194,11 +205,6 @@ export declare function useObjectLabel(): {
      * that spells the prefix out does not resolve (see `viewSuffixes`).
      */
     viewLabel: (objectName: string, viewName: string, fallback: string) => string;
-    /**
-     * Resolve translated list-view description.
-     * Convention: `{ns}.objects.{objectName}._views.{viewName}.description`.
-     */
-    viewDescription: (objectName: string, viewName: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated list-view emptyState. Returns a {title, message}
      * tuple with each field independently translated. Convention:
@@ -221,41 +227,55 @@ 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}`;
+     * 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
+     * bundle entry passes through untouched (i18next interpolates its own
+     * `{{…}}` form, never `${…}`), and the action runner fills it in from the
+     * handler's answer once the action has run.
+     */
+    actionOutcome: (objectName: string | undefined, actionName: string, outcome: string, fallback?: string) => string | undefined;
     /**
      * 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
@@ -274,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;
@@ -299,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.
      */
@@ -360,15 +408,17 @@ export declare function useSafeFieldLabel(): {
      * reaches this client — so nav labels arrive already localized. One
      * owner, not two. To translate a sidebar group, translate it there.
      *
-     * History (objectui#5197): until then this docstring promised
+     * History (`9c60144b5`): until then this docstring promised
      * `"Sales" → "销售"` for sidebar groups, and `NavigationRenderer`
      * accepted `resolveGroupLabel`/`resolveItemLabel` to wire it up. Those
      * props could never fire — the renderer's `isCustomized` guard compared a
      * node's authored label against its own `id` (`Workspace` vs
      * `grp_workspace`), which never match, so the guard was true for every
-     * real entry. The props are gone; the promise was false, not merely
-     * unused. This helper is kept as a plain key reader for a consumer that
-     * renders navigation itself — it has no first-party caller.
+     * real entry. The props are gone, and so is the guard itself
+     * (objectui#11201: the renderer no longer matches a label's text against
+     * any name); the promise was false, not merely unused. This helper is kept
+     * as a plain key reader for a consumer that renders navigation itself — it
+     * has no first-party caller.
      */
     navGroupLabel: (appName: string, groupId: string, fallback: string) => string;
     /**
@@ -405,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`.
@@ -454,11 +486,6 @@ export declare function useSafeFieldLabel(): {
      * that spells the prefix out does not resolve (see `viewSuffixes`).
      */
     viewLabel: (objectName: string, viewName: string, fallback: string) => string;
-    /**
-     * Resolve translated list-view description.
-     * Convention: `{ns}.objects.{objectName}._views.{viewName}.description`.
-     */
-    viewDescription: (objectName: string, viewName: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated list-view emptyState. Returns a {title, message}
      * tuple with each field independently translated. Convention:
@@ -481,41 +508,55 @@ 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}`;
+     * 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
+     * bundle entry passes through untouched (i18next interpolates its own
+     * `{{…}}` form, never `${…}`), and the action runner fills it in from the
+     * handler's answer once the action has run.
+     */
+    actionOutcome: (objectName: string | undefined, actionName: string, outcome: string, fallback?: string) => string | undefined;
     /**
      * 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
@@ -534,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;