@object-ui/i18n 3.0.3 → 3.1.1

package/dist/useObjectLabel.js

@@ -0,0 +1,114 @@
+/**
+ * @object-ui/i18n - Convention-based Object & Field Label i18n
+ *
+ * Provides automatic translation resolution for object metadata labels
+ * using Salesforce-style convention-based key generation.
+ *
+ * The app namespace (e.g. "crm") is discovered dynamically from loaded
+ * i18next resources — no hardcoded app names in platform code.
+ *
+ * Convention Rules:
+ * | What               | Auto-generated key                              | Fallback              |
+ * |--------------------|-------------------------------------------------|-----------------------|
+ * | Object label       | {ns}.objects.{objectName}.label                  | objectDef.label       |
+ * | Object description | {ns}.objects.{objectName}.description             | objectDef.description |
+ * | Field label        | {ns}.fields.{objectName}.{fieldName}              | field.label           |
+ *
+ * @module useObjectLabel
+ */
+import { useObjectTranslation } from './provider';
+/**
+ * Built-in Object UI top-level locale keys — not app namespaces.
+ * Update this set when new top-level platform translation keys are added
+ * to `packages/i18n/src/locales/en.ts` to prevent them from being treated
+ * as app namespaces during dynamic namespace discovery.
+ */
+const BUILTIN_KEYS = new Set([
+    'common', 'validation', 'form', 'table', 'grid', 'calendar',
+    'list', 'kanban', 'chart', 'dashboard', 'configPanel',
+    'appDesigner', 'console', 'errors', 'detail',
+]);
+/**
+ * Hook for convention-based auto-resolution of object and field labels.
+ *
+ * Automatically constructs i18n keys from object/field names and looks up
+ * translations, falling back to the plain-string label when no translation exists.
+ *
+ * The app namespace is discovered dynamically from loaded i18next resources
+ * by finding top-level keys that contain an `objects` sub-key.
+ *
+ * @example
+ * ```tsx
+ * const { objectLabel, fieldLabel } = useObjectLabel();
+ * <h1>{objectLabel(objectDef)}</h1>
+ * ```
+ */
+export function useObjectLabel() {
+    const { t, i18n } = useObjectTranslation();
+    /**
+     * Discover app namespace(s) from loaded i18next resources.
+     * Returns top-level keys (outside built-in Object UI keys) that contain
+     * an `objects` or `fields` sub-key — e.g. "crm" when resources include crm.objects.*.
+     */
+    const getAppNamespaces = () => {
+        if (!i18n || typeof i18n.getResourceBundle !== 'function')
+            return [];
+        const lang = i18n.language || 'en';
+        const bundle = i18n.getResourceBundle(lang, 'translation');
+        if (!bundle)
+            return [];
+        return Object.keys(bundle).filter((key) => !BUILTIN_KEYS.has(key) && bundle[key] && typeof bundle[key] === 'object'
+            && (bundle[key].objects || bundle[key].fields));
+    };
+    /** Try resolving a key across all discovered app namespaces. */
+    const resolve = (suffix, fallback) => {
+        try {
+            const namespaces = getAppNamespaces();
+            for (const ns of namespaces) {
+                const key = `${ns}.${suffix}`;
+                const translated = t(key, { defaultValue: '' });
+                if (translated && translated !== key && translated !== '') {
+                    return translated;
+                }
+            }
+        }
+        catch {
+            // Graceful degradation when i18n provider is not available
+        }
+        return fallback;
+    };
+    return {
+        /**
+         * Resolve translated object label, falling back to objectDef.label.
+         */
+        objectLabel: (objectDef) => resolve(`objects.${objectDef.name}.label`, objectDef.label),
+        /**
+         * Resolve translated object description, falling back to objectDef.description.
+         */
+        objectDescription: (objectDef) => {
+            if (!objectDef.description)
+                return undefined;
+            return resolve(`objects.${objectDef.name}.description`, objectDef.description);
+        },
+        /**
+         * Resolve translated field label, falling back to the provided fallback string.
+         */
+        fieldLabel: (objectName, fieldName, fallback) => resolve(`fields.${objectName}.${fieldName}`, fallback),
+    };
+}
+/**
+ * Safe wrapper for useObjectLabel that falls back to identity functions
+ * when no I18nProvider is available. Suitable for plugin components that
+ * may be rendered outside an i18n context.
+ */
+export function useSafeFieldLabel() {
+    try {
+        const { fieldLabel } = useObjectLabel();
+        return { fieldLabel };
+    }
+    catch {
+        return {
+            fieldLabel: (_objectName, _fieldName, fallback) => fallback,
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/i18n",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -20,22 +20,24 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./locales/*": {
       "types": "./dist/locales/*.d.ts",
-      "import": "./dist/locales/*.js"
+      "import": "./dist/locales/*.js",
+      "default": "./dist/locales/*.js"
     }
   },
   "dependencies": {
-    "i18next": "^25.8.7",
+    "i18next": "^25.8.13",
     "react-i18next": "^16.5.4"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "19.2.13",
+    "@types/react": "19.2.14",
     "react": "19.2.4",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/src/__tests__/useObjectLabel.test.tsx

@@ -0,0 +1,131 @@
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import React from 'react';
+import { I18nProvider } from '../provider';
+import { createI18n } from '../i18n';
+import { useObjectLabel } from '../useObjectLabel';
+
+/**
+ * Create a wrapper with custom translations to simulate CRM locale bundles.
+ */
+function createWrapper(lang: string, translations?: Record<string, unknown>) {
+  const instance = createI18n({ defaultLanguage: lang, detectBrowserLanguage: false });
+  if (translations) {
+    instance.addResourceBundle(lang, 'translation', translations, true, true);
+  }
+  return ({ children }: { children: React.ReactNode }) =>
+    React.createElement(I18nProvider, { instance }, children);
+}
+
+describe('useObjectLabel', () => {
+  describe('objectLabel', () => {
+    it('returns the plain label when no translation exists', () => {
+      const wrapper = createWrapper('en');
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      const label = result.current.objectLabel({ name: 'order_item', label: 'Order Item' });
+      expect(label).toBe('Order Item');
+    });
+
+    it('returns the translated label when a translation exists', () => {
+      const wrapper = createWrapper('zh', {
+        crm: { objects: { order_item: { label: '订单明细' } } },
+      });
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      const label = result.current.objectLabel({ name: 'order_item', label: 'Order Item' });
+      expect(label).toBe('订单明细');
+    });
+
+    it('falls back to plain label when translation key returns empty string', () => {
+      const wrapper = createWrapper('zh', {
+        crm: { objects: { order_item: { label: '' } } },
+      });
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      const label = result.current.objectLabel({ name: 'order_item', label: 'Order Item' });
+      expect(label).toBe('Order Item');
+    });
+  });
+
+  describe('objectDescription', () => {
+    it('returns undefined when objectDef has no description', () => {
+      const wrapper = createWrapper('en');
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      const desc = result.current.objectDescription({ name: 'order_item' });
+      expect(desc).toBeUndefined();
+    });
+
+    it('returns the plain description when no translation exists', () => {
+      const wrapper = createWrapper('en');
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      const desc = result.current.objectDescription({ name: 'order_item', description: 'Line items in an order' });
+      expect(desc).toBe('Line items in an order');
+    });
+
+    it('returns the translated description when a translation exists', () => {
+      const wrapper = createWrapper('zh', {
+        crm: { objects: { order_item: { description: '订单中的商品条目' } } },
+      });
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      const desc = result.current.objectDescription({ name: 'order_item', description: 'Line items in an order' });
+      expect(desc).toBe('订单中的商品条目');
+    });
+  });
+
+  describe('fieldLabel', () => {
+    it('returns the fallback label when no translation exists', () => {
+      const wrapper = createWrapper('en');
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      const label = result.current.fieldLabel('order_item', 'name', 'Line Item');
+      expect(label).toBe('Line Item');
+    });
+
+    it('returns the translated label when a translation exists', () => {
+      const wrapper = createWrapper('zh', {
+        crm: { fields: { order_item: { name: '订单项' } } },
+      });
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      const label = result.current.fieldLabel('order_item', 'name', 'Line Item');
+      expect(label).toBe('订单项');
+    });
+
+    it('falls back to plain label when translation key returns empty string', () => {
+      const wrapper = createWrapper('zh', {
+        crm: { fields: { order_item: { name: '' } } },
+      });
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      const label = result.current.fieldLabel('order_item', 'name', 'Line Item');
+      expect(label).toBe('Line Item');
+    });
+  });
+
+  describe('multiple objects', () => {
+    it('resolves labels for different objects independently', () => {
+      const wrapper = createWrapper('zh', {
+        crm: {
+          objects: {
+            contact: { label: '联系人' },
+            opportunity: { label: '商机' },
+          },
+          fields: {
+            contact: { email: '邮箱' },
+            opportunity: { stage: '阶段' },
+          },
+        },
+      });
+      const { result } = renderHook(() => useObjectLabel(), { wrapper });
+
+      expect(result.current.objectLabel({ name: 'contact', label: 'Contact' })).toBe('联系人');
+      expect(result.current.objectLabel({ name: 'opportunity', label: 'Opportunity' })).toBe('商机');
+      expect(result.current.fieldLabel('contact', 'email', 'Email')).toBe('邮箱');
+      expect(result.current.fieldLabel('opportunity', 'stage', 'Stage')).toBe('阶段');
+    });
+  });
+});

package/src/index.ts

@@ -37,6 +37,9 @@ export { createI18n, getDirection, getAvailableLanguages, type I18nConfig, type
 // React integration
 export { I18nProvider, useObjectTranslation, useI18nContext, type I18nProviderProps } from './provider';
 
+// Convention-based object/field label i18n
+export { useObjectLabel, useSafeFieldLabel } from './useObjectLabel';
+
 // Locale packs
 export { builtInLocales, isRTL, RTL_LANGUAGES } from './locales/index';
 export { default as en } from './locales/en';