@object-ui/i18n 17.5.0 → 17.7.0

package/dist/useObjectLabel.d.ts

@@ -88,13 +88,29 @@ export declare function useObjectLabel(): {
         description?: string;
     }) => string | undefined;
     /**
-     * Resolve translated label for a navigation group within an app.
-     * Convention: `{ns}.apps.{appName}.navigation.{groupId}.label`.
+     * Read `{ns}.apps.{appName}.navigation.{groupId}.label` out of the loaded
+     * CLIENT translation resources, falling back to `fallback`.
      *
-     * Mirrors `objectLabel`/`dashboardLabel` so app metadata can keep
-     * English fallbacks while translation packs supply localised
-     * sidebar group labels (e.g. "Sales" → "销售") without explicit
-     * I18nLabel `{ key, defaultValue }` annotations.
+     * ⚠️ This does NOT localize the sidebar, and adding a translation pack
+     * keyed this way will not change a single rendered nav label.
+     * **App-navigation localization is owned solely by the server-side
+     * `/meta` boundary**: `translateApp` in `@objectstack/spec`
+     * (`src/system/i18n-resolver.ts`) rewrites every navigation node's
+     * `label` by id, and `@objectstack/rest` applies it before the metadata
+     * reaches this client — so nav labels arrive already localized. One
+     * owner, not two. To translate a sidebar group, translate it there.
+     *
+     * 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, 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;
     /**
@@ -133,6 +149,29 @@ export declare function useObjectLabel(): {
      * 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.
+     */
+    widgetSubCaption: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated page label, falling back to pageDef.label.
      * Convention: `{ns}.pages.{pageName}.label`.
@@ -157,11 +196,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:
@@ -204,6 +238,20 @@ export declare function useObjectLabel(): {
      * falling back to `{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.
+     * 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).
@@ -311,13 +359,29 @@ export declare function useSafeFieldLabel(): {
         description?: string;
     }) => string | undefined;
     /**
-     * Resolve translated label for a navigation group within an app.
-     * Convention: `{ns}.apps.{appName}.navigation.{groupId}.label`.
+     * Read `{ns}.apps.{appName}.navigation.{groupId}.label` out of the loaded
+     * CLIENT translation resources, falling back to `fallback`.
      *
-     * Mirrors `objectLabel`/`dashboardLabel` so app metadata can keep
-     * English fallbacks while translation packs supply localised
-     * sidebar group labels (e.g. "Sales" → "销售") without explicit
-     * I18nLabel `{ key, defaultValue }` annotations.
+     * ⚠️ This does NOT localize the sidebar, and adding a translation pack
+     * keyed this way will not change a single rendered nav label.
+     * **App-navigation localization is owned solely by the server-side
+     * `/meta` boundary**: `translateApp` in `@objectstack/spec`
+     * (`src/system/i18n-resolver.ts`) rewrites every navigation node's
+     * `label` by id, and `@objectstack/rest` applies it before the metadata
+     * reaches this client — so nav labels arrive already localized. One
+     * owner, not two. To translate a sidebar group, translate it there.
+     *
+     * 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, 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;
     /**
@@ -356,6 +420,29 @@ export declare function useSafeFieldLabel(): {
      * 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.
+     */
+    widgetSubCaption: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated page label, falling back to pageDef.label.
      * Convention: `{ns}.pages.{pageName}.label`.
@@ -380,11 +467,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:
@@ -427,6 +509,20 @@ export declare function useSafeFieldLabel(): {
      * falling back to `{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.
+     * 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).

package/dist/useObjectLabel.js

@@ -17,8 +17,8 @@
  * @module useObjectLabel
  */
 import { useMemo } from 'react';
-import { useObjectTranslation } from './provider';
-import { I18N_PROBE_FLAG } from './i18n';
+import { useObjectTranslation } from './provider.js';
+import { I18N_PROBE_FLAG } from './i18n.js';
 /**
  * Built-in Object UI top-level locale keys — not app namespaces.
  * Update this set when new top-level platform translation keys are added
@@ -30,6 +30,41 @@ const BUILTIN_KEYS = new Set([
     'list', 'kanban', 'chart', 'dashboard', 'configPanel',
     'appDesigner', 'console', 'errors', 'detail',
 ]);
+/**
+ * Whether `i18n` is a real i18next instance rather than react-i18next's
+ * no-instance placeholder.
+ *
+ * With nothing to bind to, `useTranslation` warns `NO_I18NEXT_INSTANCE` and
+ * builds its return value out of a fresh `{}` on every render (`const
+ * finalI18n = i18n || {}`, which then feeds that hook's own `useMemo` deps), so
+ * the `i18n` we receive has a new identity each render even though nothing
+ * about it can have changed.
+ *
+ * `getResourceBundle` is the probe because it is the only instance member the
+ * resolvers below ever touch — via `getAppNamespaces`, the single gate every
+ * `t()` call in this module sits behind.
+ */
+function hasUsableI18nInstance(i18n) {
+    return Boolean(i18n) && typeof i18n?.getResourceBundle === 'function';
+}
+/**
+ * Stand-ins pinned into the memo dependency list while no i18next instance is
+ * bound, so the memo in {@link useObjectLabel} actually holds on the
+ * no-provider path (objectui#5564). Module-level, so they carry one identity
+ * for the lifetime of the process instead of one per render.
+ *
+ * Substituting them is unobservable rather than merely convenient: every `t()`
+ * call in this module sits inside a `for (… of getAppNamespaces())` loop, and
+ * `getAppNamespaces()` returns `[]` under exactly {@link hasUsableI18nInstance}
+ * — so for as long as the substitution is in effect, the closures cannot read
+ * either value at all. `NO_INSTANCE_T` still mirrors react-i18next's own
+ * not-ready `t` (honour a string `defaultValue`, otherwise echo the key) so
+ * that if that reachability argument ever stops holding, behaviour does not
+ * change silently.
+ */
+const NO_INSTANCE_T = ((key, options) => typeof options?.defaultValue === 'string' ? options.defaultValue : key);
+/** @see NO_INSTANCE_T */
+const NO_INSTANCE_I18N = Object.freeze({});
 /**
  * Hook for convention-based auto-resolution of object and field labels.
  *
@@ -46,7 +81,21 @@ const BUILTIN_KEYS = new Set([
  * ```
  */
 export function useObjectLabel() {
-    const { t, i18n } = useObjectTranslation();
+    const { t: boundT, i18n: boundI18n } = useObjectTranslation();
+    // Pin both memo dependencies to module constants while there is no i18next
+    // instance to bind to. Without this the memo below never held on exactly the
+    // no-provider path `useSafeFieldLabel` advertises: react-i18next rebuilds its
+    // return value from a fresh `{}` each render, so `i18n` arrived with a new
+    // identity every time and re-keyed every consumer memo this hook feeds
+    // (objectui#5564 measured 4 distinct identities across 4 renders). See
+    // `hasUsableI18nInstance` for why the substitution cannot be observed.
+    //
+    // When an instance does appear these become the live values again, so a
+    // provider mounting after first render recomputes the object exactly once and
+    // resolves real translations from then on.
+    const bound = hasUsableI18nInstance(boundI18n);
+    const t = bound ? boundT : NO_INSTANCE_T;
+    const i18n = bound ? boundI18n : NO_INSTANCE_I18N;
     // Memoize the entire returned object — all closures below reference `t`/`i18n`
     // and stay valid until the language changes. Returning a fresh object on every
     // render was busting downstream `useMemo`/`useCallback` deps in heavy consumers
@@ -64,7 +113,7 @@ export function useObjectLabel() {
          * (objectui#3372).
          */
         const getAppNamespaces = () => {
-            if (!i18n || typeof i18n.getResourceBundle !== 'function')
+            if (!hasUsableI18nInstance(i18n))
                 return [];
             const lang = i18n.language || 'en';
             const bundle = i18n.getResourceBundle(lang, 'translation');
@@ -193,8 +242,8 @@ export function useObjectLabel() {
          * name under `_views` — the runtime view identity's own name, stripped of the
          * object prefix. That single spelling is canonical per the objectstack#5164
          * ruling A (2026-08-06): the i18n extractor asks the view composer for the key
-         * (objectstack#6124) and `packages/lint` enforces exactly that spelling
-         * (objectstack#6038), so this resolver accepts exactly what those produce.
+         * (objectstack `b3c1f3cd5`) and `packages/lint` enforces exactly that spelling
+         * (objectstack `7618ee814`), so this resolver accepts exactly what those produce.
          *
          * Deliberately NOT a second candidate: the prefixed full name
          * (`_views.<objectName>.<viewName>`). Accepting it made this client more
@@ -267,13 +316,29 @@ export function useObjectLabel() {
                 return resolved || undefined;
             },
             /**
-             * Resolve translated label for a navigation group within an app.
-             * Convention: `{ns}.apps.{appName}.navigation.{groupId}.label`.
+             * Read `{ns}.apps.{appName}.navigation.{groupId}.label` out of the loaded
+             * CLIENT translation resources, falling back to `fallback`.
              *
-             * Mirrors `objectLabel`/`dashboardLabel` so app metadata can keep
-             * English fallbacks while translation packs supply localised
-             * sidebar group labels (e.g. "Sales" → "销售") without explicit
-             * I18nLabel `{ key, defaultValue }` annotations.
+             * ⚠️ This does NOT localize the sidebar, and adding a translation pack
+             * keyed this way will not change a single rendered nav label.
+             * **App-navigation localization is owned solely by the server-side
+             * `/meta` boundary**: `translateApp` in `@objectstack/spec`
+             * (`src/system/i18n-resolver.ts`) rewrites every navigation node's
+             * `label` by id, and `@objectstack/rest` applies it before the metadata
+             * reaches this client — so nav labels arrive already localized. One
+             * owner, not two. To translate a sidebar group, translate it there.
+             *
+             * 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, 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, groupId, fallback) => resolve(`apps.${appName}.navigation.${groupId}.label`, fallback),
             /**
@@ -314,6 +379,33 @@ export function useObjectLabel() {
                 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`.
@@ -332,15 +424,27 @@ export function useObjectLabel() {
              * that spells the prefix out does not resolve (see `viewSuffixes`).
              */
             viewLabel: (objectName, viewName, fallback) => resolve(viewSuffixes(objectName, viewName, 'label'), fallback),
-            /**
-             * Resolve translated list-view description.
-             * Convention: `{ns}.objects.{objectName}._views.{viewName}.description`.
+            /*
+             * There is deliberately NO `viewDescription` member here, and no
+             * `{ns}.objects.{objectName}._views.{viewName}.description` convention for
+             * it to resolve (objectui#7219, maintainer ruling 2026-09-02, option B).
+             *
+             * A list view's description has exactly ONE channel: the `I18nLabel` value
+             * authored on the view entry -- a string or an inline locale map -- which
+             * `ObjectView` relays and the render site resolves with `pickLocalized`
+             * (objectui#7199). The catalog key used to be declared and resolved right
+             * here, between its two wired-up siblings, but had zero callers and zero
+             * in-repo bundle usage: a bundle entry written under it reached no screen.
+             *
+             * Wiring it in instead was weighed and NOT taken -- two vocabularies for
+             * one concept plus a precedence rule is the ambiguity, not the fix. Leaving
+             * it declared and unfulfilled was not taken either; the standing rule is
+             * remove, not phase out, when a surface has measured zero use.
+             *
+             * `viewSuffixes` is NOT retired with it: `viewLabel` above and
+             * `viewEmptyState` below share that helper and keep resolving. Only the
+             * `'description'` tail passed to it is gone.
              */
-            viewDescription: (objectName, viewName, fallback) => {
-                const fb = fallback ?? '';
-                const resolved = resolve(viewSuffixes(objectName, viewName, 'description'), fb);
-                return resolved || undefined;
-            },
             /**
              * Resolve translated list-view emptyState. Returns a {title, message}
              * tuple with each field independently translated. Convention:
@@ -393,6 +497,24 @@ export function useObjectLabel() {
                 const resolved = resolve(actionSuffixes(objectName, actionName, 'successMessage'), fb);
                 return resolved || 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.
+             * 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, actionName, outcome, fallback) => {
+                const fb = fallback ?? '';
+                const resolved = resolve(actionSuffixes(objectName, actionName, `outcomeMessages.${outcome}`), fb);
+                return resolved || undefined;
+            },
             /**
              * Resolve translated action description (the explanatory line shown in the
              * action's param dialog / sheet / drawer header).
@@ -511,8 +633,11 @@ const SAFE_FIELD_LABEL_FALLBACK = {
 export function useSafeFieldLabel() {
     // useObjectLabel delegates to the provider-safe useObjectTranslation (react-
     // i18next falls back to the global instance and never throws), so it needs no
-    // try/catch — wrapping the hook call would violate rules-of-hooks. It already
-    // returns a stable memoized object; the module-level fallback stays as a
-    // defensive default, reached only if it ever returns nullish.
+    // try/catch — wrapping the hook call would violate rules-of-hooks. Its memo
+    // now holds with or without an i18next instance, so the object below is
+    // stable on both paths — it was NOT before objectui#5564, which measured a
+    // fresh object every render outside a provider, i.e. the opposite of what
+    // this wrapper advertises. The module-level fallback stays as a defensive
+    // default, reached only if it ever returns nullish.
     return useObjectLabel() ?? SAFE_FIELD_LABEL_FALLBACK;
 }

package/dist/useSafeTranslation.js

@@ -6,21 +6,38 @@
  * returning raw i18n keys — and, for a key the `defaults` map does not carry,
  * to the call site's own inline `t(key, { defaultValue })` (objectui#3865).
  * The lookup order is i18next's, so a provider-less host and a provider-mounted
- * one render the same string: `defaults[key]` (the pack value's stand-in here)
+ * one render the same string: `defaults[key_<category>]` for a numeric `count`
+ * (objectui#11445), then `defaults[key]` (the pack value's stand-in here)
  * -> `defaultValue` -> the key.
  *
  * @param defaults - Fallback English translations keyed by i18n key
  * @param testKey - A key to test if i18n is properly configured (must be in defaults)
  */
-import { useObjectTranslation } from './provider';
+import { useObjectTranslation } from './provider.js';
+import { DEFAULT_VALUE_OPTION, interpolateFallback } from './fallbackInterpolation.js';
 /**
- * The i18next option that names the string to use when the lookup misses.
+ * The plural rules the defaults tables are written in. Every table is English
+ * (the `en` pack's stand-in), so English selects the slot.
+ */
+const DEFAULTS_PLURAL_RULES = new Intl.PluralRules('en');
+/**
+ * The `defaults` row a count family answers from, the way i18next walks a pack
+ * (objectui#11445): `key_<category>` first, then the base `key`.
  *
- * It is a LOOKUP CONTROL, not interpolation data (objectui#3865): it chooses
- * which string is rendered, so it must never also be spliced into a
- * `{{defaultValue}}` hole in the string it chose — or in any other.
+ * i18next plural-selects only for a NUMERIC `count` (`needsPluralHandling` in
+ * i18next 26 is `count !== undefined && !isString(count)`), so a string count
+ * reads the base row on both paths. `_zero` is not looked up: no English row
+ * spells one, because `en` selects no `zero` category.
  */
-const DEFAULT_VALUE_OPTION = 'defaultValue';
+function defaultsRowFor(defaults, key, options) {
+    const count = options?.count;
+    if (typeof count === 'number' && Number.isFinite(count)) {
+        const slot = defaults[`${key}_${DEFAULTS_PLURAL_RULES.select(count)}`];
+        if (slot)
+            return slot;
+    }
+    return defaults[key];
+}
 export function createSafeTranslation(defaults, testKey) {
     // Factory-level fallback: one stable reference per defaults map, so
     // downstream useMemo/useCallback deps don't invalidate every render in
@@ -47,43 +64,24 @@ export function createSafeTranslation(defaults, testKey) {
         // `string`, and i18next itself declines a `null` default. `||` (not `??`)
         // keeps the whole chain consistent with the pre-existing `defaults[key] ||`
         // step: an empty string at any position falls through to the next.
+        //
+        // A count family's suffixed rows are reached here too (objectui#11445):
+        // `t('detail.replyCount', { count: 3 })` reads `detail.replyCount_other`
+        // before the base row, exactly as i18next reads the `en` pack. Before that
+        // card a family's `_one` / `_other` rows were unreachable on this path, so
+        // the code-selected `xxxCountOne` pairs were the only way a provider-less
+        // host rendered "1 reply" — the card retired those pairs.
         const inlineDefault = options?.[DEFAULT_VALUE_OPTION];
-        let value = defaults[key] || (typeof inlineDefault === 'string' ? inlineDefault : '') || key;
-        if (options) {
-            for (const [k, v] of Object.entries(options)) {
-                // Reserved: see DEFAULT_VALUE_OPTION. Skipped whatever its type, so an
-                // ignored non-string default cannot re-enter through this loop.
-                //
-                // This is the one deliberate divergence from i18next on this path, and
-                // it is unreachable with today's strings: i18next passes the whole
-                // options object to its interpolator, so it WOULD render
-                // `'Fallback: {{defaultValue}}'` as `'Fallback: INLINE'` (measured on
-                // 26.3.6) — but no value in this repo spells that hole (zero hits for
-                // `{{defaultValue` across packages/apps/examples), and splicing a
-                // fallback string into a hole named after itself has no sensible
-                // reading. The alternative — letting a call site's fallback text leak
-                // into an unrelated table value — is the worse of the two.
-                if (k === DEFAULT_VALUE_OPTION)
-                    continue;
-                // `split(needle).join(value)` — deliberately not `replace`, and not
-                // `replaceAll` either (objectui#3418). This path must agree with
-                // i18next, which serves the *provider* path; any divergence is a
-                // silent fork that only shows up on provider-less hosts, where we are
-                // least likely to see it:
-                //   1. `replace` with a string needle substitutes only the FIRST
-                //      occurrence. i18next substitutes every one, so a sentence that
-                //      repeats a placeholder ("Selected {{count}} of {{count}} items"
-                //      — natural in many locales, and often required by RTL /
-                //      agglutinative word order) leaked literal braces to users.
-                //   2. `replace` AND `replaceAll` both interpret `$&`, `` $` ``, `$'`
-                //      and `$$` in the *replacement* string. i18next does not. Values
-                //      here are runtime data — record labels, search terms — so this
-                //      one is reachable today, unlike (1).
-                // split/join is literal on both sides, which is exactly i18next's
-                // behaviour, and needs no regex escaping of the placeholder name.
-                value = value.split(`{{${k}}}`).join(String(v));
-            }
-        }
+        let value = defaultsRowFor(defaults, key, options) ||
+            (typeof inlineDefault === 'string' ? inlineDefault : '') ||
+            key;
+        // The interpolation itself lives in `fallbackInterpolation.ts` — ONE
+        // function, shared with `useObjectTranslation`'s not-ready path
+        // (objectui#6219). Both provider-less renderers therefore fill exactly
+        // the `{{name}}` spelling objectui#3512 holds the copy to, and the
+        // reserved-name rule for `defaultValue` (objectui#3865) is stated once.
+        // The behaviour pinned by `useSafeTranslation.test.tsx` is unchanged.
+        value = interpolateFallback(value, options);
         return value;
     };
     return function useSafeTranslation() {

package/dist/utils/formatting.d.ts

@@ -2,6 +2,17 @@
  * @object-ui/i18n - Date and currency formatting utilities
  *
  * Uses the native Intl API for locale-aware formatting.
+ *
+ * Every date helper below reads a string through `toDisplayDate`
+ * (`@object-ui/core`), the one parse step behind the date faces
+ * (objectui#10110, objectui#10183). The engine's own parse reads a date-only
+ * `2026-09-01` as UTC midnight, so each helper named August 31st for every
+ * viewer west of UTC (objectui#10866). The shared step tells the two shapes
+ * apart by the value: a date-only string is rebuilt at local midnight of the
+ * day it names, and a value with a time part keeps its instant. It also
+ * refuses a day its month does not have (`2026-02-30`, objectui#10026), which
+ * each helper then renders as the raw string, its face for any unparsable
+ * value.
  */
 export interface DateFormatOptions {
     locale?: string;
@@ -33,6 +44,11 @@ export declare function formatDate(date: Date | string | number, options?: DateF
 export declare function formatDateTime(date: Date | string | number, options?: DateFormatOptions): string;
 /**
  * Format a relative time (e.g., "2 days ago", "in 3 hours")
+ *
+ * A date-only value counts from now to the START of the day it names (local
+ * midnight), the same distance in every zone at the same wall-clock time.
+ * An unparsable value comes back as its string, as it does from
+ * {@link formatDate}; `Intl.RelativeTimeFormat` would throw on it.
  */
 export declare function formatRelativeTime(date: Date | string | number, locale?: string): string;
 /**

package/dist/utils/formatting.js

@@ -2,13 +2,25 @@
  * @object-ui/i18n - Date and currency formatting utilities
  *
  * Uses the native Intl API for locale-aware formatting.
+ *
+ * Every date helper below reads a string through `toDisplayDate`
+ * (`@object-ui/core`), the one parse step behind the date faces
+ * (objectui#10110, objectui#10183). The engine's own parse reads a date-only
+ * `2026-09-01` as UTC midnight, so each helper named August 31st for every
+ * viewer west of UTC (objectui#10866). The shared step tells the two shapes
+ * apart by the value: a date-only string is rebuilt at local midnight of the
+ * day it names, and a value with a time part keeps its instant. It also
+ * refuses a day its month does not have (`2026-02-30`, objectui#10026), which
+ * each helper then renders as the raw string, its face for any unparsable
+ * value.
  */
+import { toDisplayDate } from '@object-ui/core';
 /**
  * Format a date according to locale conventions
  */
 export function formatDate(date, options = {}) {
     const { locale = 'en', style = 'medium' } = options;
-    const d = date instanceof Date ? date : new Date(date);
+    const d = toDisplayDate(date);
     if (isNaN(d.getTime())) {
         return String(date);
     }
@@ -28,7 +40,7 @@ export function formatDate(date, options = {}) {
  */
 export function formatDateTime(date, options = {}) {
     const { locale = 'en', style = 'medium' } = options;
-    const d = date instanceof Date ? date : new Date(date);
+    const d = toDisplayDate(date);
     if (isNaN(d.getTime())) {
         return String(date);
     }
@@ -42,9 +54,17 @@ export function formatDateTime(date, options = {}) {
 }
 /**
  * Format a relative time (e.g., "2 days ago", "in 3 hours")
+ *
+ * A date-only value counts from now to the START of the day it names (local
+ * midnight), the same distance in every zone at the same wall-clock time.
+ * An unparsable value comes back as its string, as it does from
+ * {@link formatDate}; `Intl.RelativeTimeFormat` would throw on it.
  */
 export function formatRelativeTime(date, locale = 'en') {
-    const d = date instanceof Date ? date : new Date(date);
+    const d = toDisplayDate(date);
+    if (isNaN(d.getTime())) {
+        return String(date);
+    }
     const now = new Date();
     const diffMs = d.getTime() - now.getTime();
     const diffSec = Math.round(diffMs / 1000);

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from './formatting';
-export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, type SpecPluralRule, type SpecDateFormat, type SpecNumberFormat, type SpecLocaleConfig, } from './spec-formatters';
-export { isSpecTranslationData, transformSpecTranslations, type SpecTranslationData, } from './spec-translations';
-export { formatDisplayNumber, shouldGroupDisplayNumber, type DisplayNumberFormatOptions, } from './number-display';
+export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from './formatting.js';
+export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, type SpecPluralRule, type SpecDateFormat, type SpecNumberFormat, type SpecLocaleConfig, } from './spec-formatters.js';
+export { isSpecTranslationData, transformSpecTranslations, type SpecTranslationData, } from './spec-translations.js';
+export { formatDisplayNumber, shouldGroupDisplayNumber, type DisplayNumberFormatOptions, } from './number-display.js';