@object-ui/i18n 16.0.0 → 16.1.0

package/dist/useObjectLabel.d.ts

@@ -204,6 +204,28 @@ export declare function useObjectLabel(): {
      * 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, then 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
+     * is fetched whole with `returnObjects` and indexed directly — never
+     * resolved through a dotted i18next key.
+     */
+    actionResultDialog: <T extends {
+        title?: string;
+        description?: string;
+        acknowledge?: string;
+        fields?: Array<{
+            path: string;
+            label?: string;
+            [key: string]: any;
+        }>;
+    }>(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}`.
@@ -224,17 +246,211 @@ export declare function useObjectLabel(): {
  * may be rendered outside an i18n context.
  */
 export declare function useSafeFieldLabel(): {
-    fieldLabel: (_objectName: string, _fieldName: string, fallback: string) => string;
-    translateOptions: (_objectName: string, _fieldName: string, options: Array<{
+    /**
+     * Resolve translated object label, falling back to objectDef.label.
+     */
+    objectLabel: (objectDef: {
+        name: string;
+        label: string;
+    }) => string;
+    /**
+     * Resolve translated object description, falling back to objectDef.description.
+     */
+    objectDescription: (objectDef: {
+        name: string;
+        description?: string;
+    }) => string | undefined;
+    /**
+     * Resolve translated field label, falling back to the provided fallback string.
+     */
+    fieldLabel: (objectName: string, fieldName: string, fallback: string) => string;
+    /**
+     * Resolve a translated select option label for a given object field.
+     * Falls back to the provided fallback (usually the English option label).
+     */
+    fieldOptionLabel: (objectName: string, fieldName: string, optionValue: string, fallback: string) => string;
+    /**
+     * Translate all options for a given field, returning a new options array
+     * with translated labels. Pass the objectName and fieldName to look up
+     * translations; the original label is used as fallback.
+     */
+    translateOptions: (objectName: string, fieldName: string, options: Array<{
         value: string;
         label: string;
         [key: string]: any;
-    }>) => {
-        [key: string]: any;
+    }>) => Array<{
         value: string;
         label: string;
-    }[];
-    fieldOptionLabel: (_objectName: string, _fieldName: string, _optionValue: string, fallback: string) => string;
-    sectionLabel: (_objectName: string, _sectionName: string, fallback: string) => string;
-    actionLabel: (_objectName: string | undefined, _actionName: string, fallback: string) => string;
+        [key: string]: any;
+    }>;
+    /**
+     * Resolve translated app label, falling back to appDef.label.
+     * Looks up `{ns}.apps.{appName}.label` from loaded i18next resources.
+     */
+    appLabel: (appDef: {
+        name: string;
+        label?: string;
+    }) => string;
+    /**
+     * Resolve translated app description, falling back to appDef.description.
+     * Returns the translated value even when metadata has no description —
+     * translation-only descriptions (defined only in i18n bundles) are common
+     * in examples where the app metadata is English-only.
+     */
+    appDescription: (appDef: {
+        name: string;
+        description?: string;
+    }) => string | undefined;
+    /**
+     * Resolve translated label for a navigation group within an app.
+     * Convention: `{ns}.apps.{appName}.navigation.{groupId}.label`.
+     *
+     * 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.
+     */
+    navGroupLabel: (appName: string, groupId: string, fallback: string) => string;
+    /**
+     * Resolve translated dashboard label, falling back to dashboardDef.label.
+     * Convention: `{ns}.dashboards.{dashboardName}.label`.
+     */
+    dashboardLabel: (dashboardDef: {
+        name: string;
+        label?: string;
+    }) => string;
+    /**
+     * Resolve translated dashboard description, falling back to
+     * dashboardDef.description. Returns undefined when neither metadata nor
+     * translation provides one.
+     * Convention: `{ns}.dashboards.{dashboardName}.description`.
+     */
+    dashboardDescription: (dashboardDef: {
+        name: string;
+        description?: string;
+    }) => string | undefined;
+    /**
+     * Resolve translated dashboard header-action label.
+     * Convention: `{ns}.dashboards.{dashboardName}.actions.{actionKey}.label`.
+     * The actionKey is typically the action's `actionUrl` (e.g.
+     * `create_opportunity`) or its English label slugified.
+     */
+    dashboardActionLabel: (dashboardName: string, actionKey: string, fallback: string) => string;
+    /**
+     * Resolve translated widget title within a dashboard.
+     * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.title`.
+     */
+    widgetTitle: (dashboardName: string, widgetId: string, fallback: string) => string;
+    /**
+     * 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 translated page label, falling back to pageDef.label.
+     * Convention: `{ns}.pages.{pageName}.label`.
+     */
+    pageLabel: (pageDef: {
+        name: string;
+        label?: string;
+    }) => string;
+    /**
+     * Resolve translated report label, falling back to reportDef.label.
+     * Convention: `{ns}.reports.{reportName}.label`.
+     */
+    reportLabel: (reportDef: {
+        name: string;
+        label?: string;
+    }) => string;
+    /**
+     * Resolve translated list-view label.
+     * Convention (per @objectstack/spec): `{ns}.objects.{objectName}._views.{viewName}.label`.
+     */
+    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:
+     *   `{ns}.objects.{objectName}._views.{viewName}.emptyState.title`
+     *   `{ns}.objects.{objectName}._views.{viewName}.emptyState.message`
+     */
+    viewEmptyState: (objectName: string, viewName: string, fallback: {
+        title?: string;
+        message?: string;
+        icon?: string;
+    } | undefined) => {
+        title: string | undefined;
+        message: string | undefined;
+        icon?: string;
+    } | undefined;
+    /**
+     * Resolve translated form-section label.
+     * Convention: `{ns}.objects.{objectName}._sections.{sectionName}.label`.
+     */
+    sectionLabel: (objectName: string, sectionName: string, fallback: string) => string;
+    /**
+     * Resolve translated action label.
+     * Convention: `{ns}.objects.{objectName}._actions.{actionName}.label`.
+     * Falls back to `{ns}.globalActions.{actionName}.label` when objectName is omitted.
+     */
+    actionLabel: (objectName: string | undefined, actionName: string, fallback: string) => string;
+    /**
+     * Resolve translated action confirmation prompt.
+     * Convention: `{ns}.objects.{objectName}._actions.{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`.
+     */
+    actionSuccess: (objectName: string | undefined, actionName: 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.
+     */
+    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, then 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
+     * is fetched whole with `returnObjects` and indexed directly — never
+     * resolved through a dotted i18next key.
+     */
+    actionResultDialog: <T extends {
+        title?: string;
+        description?: string;
+        acknowledge?: string;
+        fields?: Array<{
+            path: string;
+            label?: string;
+            [key: string]: any;
+        }>;
+    }>(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}`.
+     * 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}`.
+     * 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

@@ -349,6 +349,67 @@ export function useObjectLabel() {
                 const resolved = resolve(suffixes, fb);
                 return resolved || 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, then 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
+             * is fetched whole with `returnObjects` and indexed directly — never
+             * resolved through a dotted i18next key.
+             */
+            actionResultDialog: (objectName, actionName, spec) => {
+                if (!spec || !actionName)
+                    return spec;
+                const suffixesFor = (attr) => {
+                    const tail = `_actions.${actionName}.resultDialog.${attr}`;
+                    return objectName
+                        ? objectSuffixes(objectName, tail)
+                        : [`globalActions.${actionName}.resultDialog.${attr}`];
+                };
+                const textFor = (attr) => {
+                    const resolved = resolve(suffixesFor(attr), spec[attr] ?? '');
+                    return resolved || spec[attr];
+                };
+                const fieldsMap = (() => {
+                    try {
+                        for (const ns of getAppNamespaces()) {
+                            for (const suffix of suffixesFor('fields')) {
+                                const node = t(`${ns}.${suffix}`, {
+                                    returnObjects: true,
+                                    defaultValue: null,
+                                    [I18N_PROBE_FLAG]: true,
+                                });
+                                if (node && typeof node === 'object' && !Array.isArray(node)) {
+                                    return node;
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Graceful degradation when i18n provider is not available
+                    }
+                    return undefined;
+                })();
+                const fields = Array.isArray(spec.fields)
+                    ? spec.fields.map((field) => {
+                        if (!field || typeof field.path !== 'string')
+                            return field;
+                        const label = fieldsMap?.[field.path];
+                        return typeof label === 'string' && label.length > 0 ? { ...field, label } : field;
+                    })
+                    : spec.fields;
+                return {
+                    ...spec,
+                    title: textFor('title'),
+                    description: textFor('description'),
+                    acknowledge: textFor('acknowledge'),
+                    fields,
+                };
+            },
             /**
              * Resolve translated action-PARAMETER text (label / placeholder / helpText).
              * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.{attr}`.
@@ -402,15 +463,10 @@ const SAFE_FIELD_LABEL_FALLBACK = {
  * may be rendered outside an i18n context.
  */
 export function useSafeFieldLabel() {
-    let resolved = null;
-    try {
-        resolved = useObjectLabel();
-    }
-    catch {
-        resolved = null;
-    }
-    // useObjectLabel already returns a stable (memoized) object per language —
-    // pass-through avoids creating a fresh wrapper here. The module-level
-    // fallback object is reused when no provider is mounted.
-    return resolved ?? SAFE_FIELD_LABEL_FALLBACK;
+    // 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.
+    return useObjectLabel() ?? SAFE_FIELD_LABEL_FALLBACK;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/i18n",
-  "version": "16.0.0",
+  "version": "16.1.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "i18next": "^26.3.6",
-    "react-i18next": "^17.0.9"
+    "react-i18next": "^17.0.10"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"