@object-ui/i18n 6.2.3 → 7.0.0

package/dist/pickLocalized.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve a possibly-localized value to the best string for a language.
+ *
+ * Accepts a plain string (passed through) or an i18n object keyed by language
+ * code — e.g. `{ en: 'Pricing', 'zh-CN': '定价', zh: '定价', default: 'Pricing' }`.
+ * Resolution order: exact language -> base language (`zh-CN` -> `zh`) -> `default`
+ * -> `en` -> first value. Unlike a `default`/`en`-only resolver this is genuinely
+ * locale-aware, so server-driven metadata (page text, action param labels) can
+ * carry inline translations instead of rendering "[object Object]" or English.
+ *
+ * Pure — pair it with `useObjectTranslation().language` (or any current-locale
+ * source) at the call site.
+ */
+export declare function pickLocalized(value: unknown, language: string | undefined | null): string;

package/dist/pickLocalized.js

@@ -0,0 +1,33 @@
+/**
+ * Resolve a possibly-localized value to the best string for a language.
+ *
+ * Accepts a plain string (passed through) or an i18n object keyed by language
+ * code — e.g. `{ en: 'Pricing', 'zh-CN': '定价', zh: '定价', default: 'Pricing' }`.
+ * Resolution order: exact language -> base language (`zh-CN` -> `zh`) -> `default`
+ * -> `en` -> first value. Unlike a `default`/`en`-only resolver this is genuinely
+ * locale-aware, so server-driven metadata (page text, action param labels) can
+ * carry inline translations instead of rendering "[object Object]" or English.
+ *
+ * Pure — pair it with `useObjectTranslation().language` (or any current-locale
+ * source) at the call site.
+ */
+export function pickLocalized(value, language) {
+    if (value == null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'object') {
+        const o = value;
+        const lang = (language || 'en').trim();
+        const base = lang.split('-')[0];
+        const pick = o[lang] ??
+            o[base] ??
+            o.default ??
+            o.en ??
+            Object.values(o).find((v) => typeof v === 'string');
+        return pick == null ? '' : String(pick);
+    }
+    return String(value);
+}

package/dist/useObjectLabel.d.ts

@@ -196,6 +196,27 @@ export declare function useObjectLabel(): {
      * 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 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;
 };
 /**
  * Safe wrapper for useObjectLabel that falls back to identity functions

package/dist/useObjectLabel.js

@@ -18,6 +18,7 @@
  */
 import { useMemo } from 'react';
 import { useObjectTranslation } from './provider';
+import { I18N_PROBE_FLAG } from './i18n';
 /**
  * Built-in Object UI top-level locale keys — not app namespaces.
  * Update this set when new top-level platform translation keys are added
@@ -88,7 +89,10 @@ export function useObjectLabel() {
                 for (const ns of namespaces) {
                     for (const suffix of suffixList) {
                         const key = `${ns}.${suffix}`;
-                        const translated = t(key, { defaultValue: '' });
+                        // `I18N_PROBE_FLAG` marks this as a speculative convention lookup so
+                        // the dev missing-key warner stays silent when it (expectedly) misses
+                        // and we fall back to the server-resolved label.
+                        const translated = t(key, { defaultValue: '', [I18N_PROBE_FLAG]: true });
                         if (translated && translated !== key && translated !== '') {
                             return translated;
                         }
@@ -328,6 +332,54 @@ export function useObjectLabel() {
                 const resolved = resolve(suffixes, fb);
                 return resolved || 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, actionName, fallback) => {
+                const fb = fallback ?? '';
+                if (!actionName)
+                    return fb || undefined;
+                const suffixes = objectName
+                    ? objectSuffixes(objectName, `_actions.${actionName}.description`)
+                    : `globalActions.${actionName}.description`;
+                const resolved = resolve(suffixes, fb);
+                return resolved || 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, actionName, paramName, attr, fallback) => {
+                const fb = fallback ?? '';
+                if (!actionName || !paramName)
+                    return fb || undefined;
+                const suffix = `_actions.${actionName}.params.${paramName}.${attr}`;
+                const suffixes = objectName
+                    ? objectSuffixes(objectName, suffix)
+                    : `globalActions.${actionName}.params.${paramName}.${attr}`;
+                const resolved = resolve(suffixes, fb);
+                return resolved || 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, actionName, paramName, optionValue, fallback) => {
+                if (!actionName || !paramName)
+                    return fallback;
+                const suffix = `_actions.${actionName}.params.${paramName}.options.${optionValue}`;
+                const suffixes = objectName
+                    ? objectSuffixes(objectName, suffix)
+                    : `globalActions.${actionName}.params.${paramName}.options.${optionValue}`;
+                return resolve(suffixes, fallback);
+            },
         };
     }, [t, i18n]);
 }

package/dist/useSafeTranslation.d.ts

@@ -3,3 +3,16 @@ export declare function createSafeTranslation(defaults: Record<string, string>,
 } | {
     t: import("i18next").TFunction<string, undefined>;
 };
+/**
+ * Per-call graceful translate hook for plugin renderers.
+ *
+ * Returns `t(keyOrKeys, fallback)`: tries each i18n key in order and returns the
+ * first real translation; when no `I18nProvider` is mounted (tests / standalone)
+ * or every key is missing, returns the English `fallback` — never a raw key.
+ *
+ * Unlike {@link createSafeTranslation} (a factory keyed by a defaults map), this
+ * takes the English default at each call site, which suits one-off labels like
+ * "Total". The key-array form supports a migration fallback chain, e.g.
+ * `tt(['common.total', 'dashboard.total'], 'Total')`.
+ */
+export declare function useSafeTranslate(): (keyOrKeys: string | string[], fallback: string) => string;

package/dist/useSafeTranslation.js

@@ -44,3 +44,35 @@ export function createSafeTranslation(defaults, testKey) {
         }
     };
 }
+/**
+ * Per-call graceful translate hook for plugin renderers.
+ *
+ * Returns `t(keyOrKeys, fallback)`: tries each i18n key in order and returns the
+ * first real translation; when no `I18nProvider` is mounted (tests / standalone)
+ * or every key is missing, returns the English `fallback` — never a raw key.
+ *
+ * Unlike {@link createSafeTranslation} (a factory keyed by a defaults map), this
+ * takes the English default at each call site, which suits one-off labels like
+ * "Total". The key-array form supports a migration fallback chain, e.g.
+ * `tt(['common.total', 'dashboard.total'], 'Total')`.
+ */
+export function useSafeTranslate() {
+    let t;
+    try {
+        t = useObjectTranslation().t;
+    }
+    catch {
+        t = undefined;
+    }
+    return (keyOrKeys, fallback) => {
+        if (!t)
+            return fallback;
+        const keys = Array.isArray(keyOrKeys) ? keyOrKeys : [keyOrKeys];
+        for (const key of keys) {
+            const v = t(key);
+            if (v && v !== key)
+                return v;
+        }
+        return fallback;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/i18n",
-  "version": "6.2.3",
+  "version": "7.0.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -30,17 +30,17 @@
     }
   },
   "dependencies": {
-    "i18next": "^26.2.0",
-    "react-i18next": "^17.0.7"
+    "i18next": "^26.3.1",
+    "react-i18next": "^17.0.8"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "19.2.15",
-    "react": "19.2.6",
+    "@types/react": "19.2.17",
+    "react": "19.2.7",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.9"
   },
   "keywords": [
     "objectui",