@object-ui/i18n 0.5.0 → 3.0.0

package/dist/locales/zh.d.ts

@@ -98,6 +98,79 @@ declare const zh: {
         readonly saveLayout: "保存布局";
         readonly resetLayout: "重置布局";
     };
+    readonly console: {
+        readonly title: "ObjectStack 控制台";
+        readonly initializing: "正在初始化应用程序...";
+        readonly loadingSteps: {
+            readonly connecting: "正在连接数据源";
+            readonly loadingConfig: "正在加载配置";
+            readonly preparingWorkspace: "正在准备工作区";
+        };
+        readonly shortcuts: {
+            readonly title: "键盘快捷键";
+            readonly description: "所有可用键盘快捷键的快速参考。";
+            readonly groups: {
+                readonly general: "通用";
+                readonly navigation: "导航";
+                readonly dataViews: "数据视图";
+                readonly preferences: "偏好设置";
+            };
+            readonly openCommandPalette: "打开命令面板";
+            readonly showShortcuts: "显示键盘快捷键";
+            readonly closeDialog: "关闭对话框/面板";
+            readonly toggleSidebar: "切换侧边栏";
+            readonly focusSearch: "聚焦搜索";
+            readonly createRecord: "新建记录";
+            readonly refreshData: "刷新数据";
+            readonly editRecord: "编辑选中记录";
+            readonly toggleDarkMode: "切换深色模式";
+        };
+        readonly commandPalette: {
+            readonly placeholder: "输入命令或搜索...";
+            readonly noResults: "未找到结果。";
+            readonly objects: "对象";
+            readonly dashboards: "仪表盘";
+            readonly pages: "页面";
+            readonly reports: "报表";
+            readonly switchApp: "切换应用";
+            readonly current: "当前";
+            readonly preferences: "偏好设置";
+            readonly lightTheme: "浅色主题";
+            readonly darkTheme: "深色主题";
+            readonly systemTheme: "系统主题";
+            readonly actions: "操作";
+            readonly openFullSearch: "打开完整搜索页面";
+        };
+        readonly errors: {
+            readonly somethingWentWrong: "出错了";
+            readonly unexpectedError: "渲染此视图时发生意外错误。";
+            readonly tryAgain: "重试";
+            readonly goHome: "返回首页";
+            readonly errorDetails: "错误详情（仅开发模式）";
+        };
+        readonly theme: {
+            readonly toggle: "切换主题";
+            readonly light: "浅色";
+            readonly dark: "深色";
+            readonly system: "系统";
+        };
+        readonly objectView: {
+            readonly objectNotFound: "未找到对象";
+            readonly objectNotFoundDescription: "对象\"{{objectName}}\"在当前配置中不存在。";
+            readonly objectNotFoundHint: "请检查您的应用导航设置或从侧边栏选择其他对象。";
+            readonly allRecords: "所有记录";
+            readonly exitDesignMode: "退出设计模式";
+            readonly enterDesignMode: "进入设计模式";
+            readonly metadataInspector: "元数据检查器";
+            readonly editView: "编辑视图";
+            readonly addView: "添加视图";
+            readonly designTools: "设计工具";
+            readonly new: "新建";
+        };
+        readonly localeSwitcher: {
+            readonly label: "语言";
+        };
+    };
     readonly errors: {
         readonly networkError: "网络错误，请检查网络连接。";
         readonly serverError: "服务器错误，请稍后重试。";

package/dist/locales/zh.js

@@ -98,6 +98,79 @@ const zh = {
         saveLayout: '保存布局',
         resetLayout: '重置布局',
     },
+    console: {
+        title: 'ObjectStack 控制台',
+        initializing: '正在初始化应用程序...',
+        loadingSteps: {
+            connecting: '正在连接数据源',
+            loadingConfig: '正在加载配置',
+            preparingWorkspace: '正在准备工作区',
+        },
+        shortcuts: {
+            title: '键盘快捷键',
+            description: '所有可用键盘快捷键的快速参考。',
+            groups: {
+                general: '通用',
+                navigation: '导航',
+                dataViews: '数据视图',
+                preferences: '偏好设置',
+            },
+            openCommandPalette: '打开命令面板',
+            showShortcuts: '显示键盘快捷键',
+            closeDialog: '关闭对话框/面板',
+            toggleSidebar: '切换侧边栏',
+            focusSearch: '聚焦搜索',
+            createRecord: '新建记录',
+            refreshData: '刷新数据',
+            editRecord: '编辑选中记录',
+            toggleDarkMode: '切换深色模式',
+        },
+        commandPalette: {
+            placeholder: '输入命令或搜索...',
+            noResults: '未找到结果。',
+            objects: '对象',
+            dashboards: '仪表盘',
+            pages: '页面',
+            reports: '报表',
+            switchApp: '切换应用',
+            current: '当前',
+            preferences: '偏好设置',
+            lightTheme: '浅色主题',
+            darkTheme: '深色主题',
+            systemTheme: '系统主题',
+            actions: '操作',
+            openFullSearch: '打开完整搜索页面',
+        },
+        errors: {
+            somethingWentWrong: '出错了',
+            unexpectedError: '渲染此视图时发生意外错误。',
+            tryAgain: '重试',
+            goHome: '返回首页',
+            errorDetails: '错误详情（仅开发模式）',
+        },
+        theme: {
+            toggle: '切换主题',
+            light: '浅色',
+            dark: '深色',
+            system: '系统',
+        },
+        objectView: {
+            objectNotFound: '未找到对象',
+            objectNotFoundDescription: '对象"{{objectName}}"在当前配置中不存在。',
+            objectNotFoundHint: '请检查您的应用导航设置或从侧边栏选择其他对象。',
+            allRecords: '所有记录',
+            exitDesignMode: '退出设计模式',
+            enterDesignMode: '进入设计模式',
+            metadataInspector: '元数据检查器',
+            editView: '编辑视图',
+            addView: '添加视图',
+            designTools: '设计工具',
+            new: '新建',
+        },
+        localeSwitcher: {
+            label: '语言',
+        },
+    },
     errors: {
         networkError: '网络错误，请检查网络连接。',
         serverError: '服务器错误，请稍后重试。',

package/dist/provider.d.ts

@@ -21,6 +21,24 @@ export interface I18nProviderProps {
     config?: I18nConfig;
     /** Pre-created i18next instance (overrides config) */
     instance?: I18nInstance;
+    /**
+     * Dynamic language pack loader (v2.0.7).
+     * When set, language packs are loaded lazily instead of being bundled.
+     * Should return a translation resource object for the given language code.
+     *
+     * @example
+     * ```tsx
+     * <I18nProvider
+     *   loadLanguage={async (lang) => {
+     *     const mod = await import(`./locales/${lang}.json`);
+     *     return mod.default;
+     *   }}
+     * >
+     *   <App />
+     * </I18nProvider>
+     * ```
+     */
+    loadLanguage?: (lang: string) => Promise<Record<string, unknown>>;
     /** Children to render */
     children: React.ReactNode;
 }
@@ -34,7 +52,7 @@ export interface I18nProviderProps {
  * </I18nProvider>
  * ```
  */
-export declare function I18nProvider({ config, instance: externalInstance, children }: I18nProviderProps): React.FunctionComponentElement<React.ProviderProps<I18nContextValue | null>>;
+export declare function I18nProvider({ config, instance: externalInstance, loadLanguage, children }: I18nProviderProps): React.FunctionComponentElement<React.ProviderProps<I18nContextValue | null>>;
 /**
  * Hook to access Object UI i18n context
  *

package/dist/provider.js

@@ -17,8 +17,8 @@ const ObjectI18nContext = createContext(null);
  * </I18nProvider>
  * ```
  */
-export function I18nProvider({ config, instance: externalInstance, children }) {
-    const i18nInstance = useMemo(() => externalInstance || createI18n(config), [externalInstance]);
+export function I18nProvider({ config, instance: externalInstance, loadLanguage, children }) {
+    const i18nInstance = useMemo(() => externalInstance || createI18n(config), [externalInstance, config]);
     const [language, setLanguage] = useState(i18nInstance.language || 'en');
     const direction = getDirection(language);
     useEffect(() => {
@@ -38,11 +38,16 @@ export function I18nProvider({ config, instance: externalInstance, children }) {
     const contextValue = useMemo(() => ({
         language,
         changeLanguage: async (lang) => {
+            // Dynamic language pack loading (v2.0.7)
+            if (loadLanguage && !i18nInstance.hasResourceBundle(lang, 'translation')) {
+                const resources = await loadLanguage(lang);
+                i18nInstance.addResourceBundle(lang, 'translation', resources, true, true);
+            }
             await i18nInstance.changeLanguage(lang);
         },
         direction,
         i18n: i18nInstance,
-    }), [language, direction, i18nInstance]);
+    }), [language, direction, i18nInstance, loadLanguage]);
     return React.createElement(ObjectI18nContext.Provider, { value: contextValue }, React.createElement(I18nextProvider, { i18n: i18nInstance }, children));
 }
 /**

package/dist/utils/index.d.ts

@@ -1 +1,2 @@
 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';

package/dist/utils/index.js

@@ -1 +1,2 @@
 export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from './formatting';
+export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, } from './spec-formatters';

package/dist/utils/spec-formatters.d.ts

@@ -0,0 +1,140 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * @object-ui/i18n - Spec-aligned i18n utilities
+ *
+ * Runtime consumers for @objectstack/spec v2.0.7 i18n types:
+ * - PluralRuleSchema → resolvePlural()
+ * - DateFormatSchema → formatDateSpec()
+ * - NumberFormatSchema → formatNumberSpec()
+ * - LocaleConfigSchema → applyLocaleConfig()
+ *
+ * @module spec-formatters
+ */
+/**
+ * Spec-aligned PluralRule (mirrors @objectstack/spec PluralRuleSchema).
+ */
+export interface SpecPluralRule {
+    /** Translation key */
+    key: string;
+    /** Form for zero items */
+    zero?: string;
+    /** Form for exactly one item */
+    one?: string;
+    /** Form for exactly two items */
+    two?: string;
+    /** Form for few items (language-specific) */
+    few?: string;
+    /** Form for many items (language-specific) */
+    many?: string;
+    /** Default/fallback form (required) */
+    other: string;
+}
+/**
+ * Resolve a plural form based on count, following CLDR plural rules.
+ * Uses the Intl.PluralRules API for correct locale-aware pluralization.
+ *
+ * @example
+ * ```ts
+ * const rule: SpecPluralRule = {
+ *   key: 'items.count',
+ *   zero: 'No items',
+ *   one: '{count} item',
+ *   other: '{count} items',
+ * };
+ * resolvePlural(rule, 0, 'en'); // → 'No items'
+ * resolvePlural(rule, 1, 'en'); // → '1 item'
+ * resolvePlural(rule, 5, 'en'); // → '5 items'
+ * ```
+ */
+export declare function resolvePlural(rule: SpecPluralRule, count: number, locale?: string): string;
+/**
+ * Spec-aligned DateFormat (mirrors @objectstack/spec DateFormatSchema).
+ */
+export interface SpecDateFormat {
+    dateStyle?: 'full' | 'long' | 'medium' | 'short';
+    timeStyle?: 'full' | 'long' | 'medium' | 'short';
+    timeZone?: string;
+    hour12?: boolean;
+}
+/**
+ * Format a date using @objectstack/spec DateFormatSchema configuration.
+ *
+ * @example
+ * ```ts
+ * formatDateSpec(new Date(), {
+ *   dateStyle: 'medium',
+ *   timeStyle: 'short',
+ *   timeZone: 'America/New_York',
+ * }, 'en-US');
+ * ```
+ */
+export declare function formatDateSpec(date: Date | string | number, format: SpecDateFormat, locale?: string): string;
+/**
+ * Spec-aligned NumberFormat (mirrors @objectstack/spec NumberFormatSchema).
+ */
+export interface SpecNumberFormat {
+    style?: 'currency' | 'percent' | 'decimal' | 'unit';
+    currency?: string;
+    unit?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+}
+/**
+ * Format a number using @objectstack/spec NumberFormatSchema configuration.
+ *
+ * @example
+ * ```ts
+ * formatNumberSpec(1234.56, {
+ *   style: 'currency',
+ *   currency: 'USD',
+ *   maximumFractionDigits: 2,
+ * }, 'en-US'); // → '$1,234.56'
+ * ```
+ */
+export declare function formatNumberSpec(value: number, format: SpecNumberFormat, locale?: string): string;
+/**
+ * Spec-aligned LocaleConfig (mirrors @objectstack/spec LocaleConfigSchema).
+ */
+export interface SpecLocaleConfig {
+    /** BCP 47 language code (e.g., 'en-US', 'zh-CN') */
+    code: string;
+    /** Fallback locale chain */
+    fallbackChain?: string[];
+    /** Text direction */
+    direction?: 'ltr' | 'rtl';
+    /** Number formatting defaults */
+    numberFormat?: SpecNumberFormat;
+    /** Date formatting defaults */
+    dateFormat?: SpecDateFormat;
+}
+/**
+ * Apply a LocaleConfigSchema to configure i18n formatting defaults.
+ * Returns resolved formatting functions bound to the locale config.
+ *
+ * @example
+ * ```ts
+ * const locale = applyLocaleConfig({
+ *   code: 'zh-CN',
+ *   direction: 'ltr',
+ *   numberFormat: { style: 'decimal', useGrouping: true },
+ *   dateFormat: { dateStyle: 'medium' },
+ * });
+ * locale.formatDate(new Date()); // Chinese medium date
+ * locale.formatNumber(1234.5);   // 1,234.5
+ * ```
+ */
+export declare function applyLocaleConfig(config: SpecLocaleConfig): {
+    code: string;
+    direction: "ltr" | "rtl";
+    fallbackChain: string[];
+    formatDate: (date: Date | string | number, overrides?: Partial<SpecDateFormat>) => string;
+    formatNumber: (value: number, overrides?: Partial<SpecNumberFormat>) => string;
+    resolvePlural: (rule: SpecPluralRule, count: number) => string;
+};

package/dist/utils/spec-formatters.js

@@ -0,0 +1,118 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Resolve a plural form based on count, following CLDR plural rules.
+ * Uses the Intl.PluralRules API for correct locale-aware pluralization.
+ *
+ * @example
+ * ```ts
+ * const rule: SpecPluralRule = {
+ *   key: 'items.count',
+ *   zero: 'No items',
+ *   one: '{count} item',
+ *   other: '{count} items',
+ * };
+ * resolvePlural(rule, 0, 'en'); // → 'No items'
+ * resolvePlural(rule, 1, 'en'); // → '1 item'
+ * resolvePlural(rule, 5, 'en'); // → '5 items'
+ * ```
+ */
+export function resolvePlural(rule, count, locale = 'en') {
+    const pr = new Intl.PluralRules(locale);
+    const category = pr.select(count);
+    // Prefer the explicit form, fall back to 'other'
+    const template = (category === 'zero' && rule.zero) ||
+        (category === 'one' && rule.one) ||
+        (category === 'two' && rule.two) ||
+        (category === 'few' && rule.few) ||
+        (category === 'many' && rule.many) ||
+        rule.other;
+    // Replace {count} placeholder
+    return template.replace(/\{count\}/g, String(count));
+}
+/**
+ * Format a date using @objectstack/spec DateFormatSchema configuration.
+ *
+ * @example
+ * ```ts
+ * formatDateSpec(new Date(), {
+ *   dateStyle: 'medium',
+ *   timeStyle: 'short',
+ *   timeZone: 'America/New_York',
+ * }, 'en-US');
+ * ```
+ */
+export function formatDateSpec(date, format, locale = 'en') {
+    const d = date instanceof Date ? date : new Date(date);
+    if (isNaN(d.getTime()))
+        return String(date);
+    const options = {};
+    if (format.dateStyle)
+        options.dateStyle = format.dateStyle;
+    if (format.timeStyle)
+        options.timeStyle = format.timeStyle;
+    if (format.timeZone)
+        options.timeZone = format.timeZone;
+    if (format.hour12 !== undefined)
+        options.hour12 = format.hour12;
+    return new Intl.DateTimeFormat(locale, options).format(d);
+}
+/**
+ * Format a number using @objectstack/spec NumberFormatSchema configuration.
+ *
+ * @example
+ * ```ts
+ * formatNumberSpec(1234.56, {
+ *   style: 'currency',
+ *   currency: 'USD',
+ *   maximumFractionDigits: 2,
+ * }, 'en-US'); // → '$1,234.56'
+ * ```
+ */
+export function formatNumberSpec(value, format, locale = 'en') {
+    const options = {
+        style: format.style || 'decimal',
+    };
+    if (format.currency)
+        options.currency = format.currency;
+    if (format.unit)
+        options.unit = format.unit;
+    if (format.minimumFractionDigits !== undefined)
+        options.minimumFractionDigits = format.minimumFractionDigits;
+    if (format.maximumFractionDigits !== undefined)
+        options.maximumFractionDigits = format.maximumFractionDigits;
+    if (format.useGrouping !== undefined)
+        options.useGrouping = format.useGrouping;
+    return new Intl.NumberFormat(locale, options).format(value);
+}
+/**
+ * Apply a LocaleConfigSchema to configure i18n formatting defaults.
+ * Returns resolved formatting functions bound to the locale config.
+ *
+ * @example
+ * ```ts
+ * const locale = applyLocaleConfig({
+ *   code: 'zh-CN',
+ *   direction: 'ltr',
+ *   numberFormat: { style: 'decimal', useGrouping: true },
+ *   dateFormat: { dateStyle: 'medium' },
+ * });
+ * locale.formatDate(new Date()); // Chinese medium date
+ * locale.formatNumber(1234.5);   // 1,234.5
+ * ```
+ */
+export function applyLocaleConfig(config) {
+    return {
+        code: config.code,
+        direction: config.direction || 'ltr',
+        fallbackChain: config.fallbackChain || [],
+        formatDate: (date, overrides) => formatDateSpec(date, { ...config.dateFormat, ...overrides }, config.code),
+        formatNumber: (value, overrides) => formatNumberSpec(value, { ...config.numberFormat, ...overrides }, config.code),
+        resolvePlural: (rule, count) => resolvePlural(rule, count, config.code),
+    };
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@object-ui/i18n",
-  "version": "0.5.0",
+  "version": "3.0.0",
   "type": "module",
+  "sideEffects": false,
   "license": "MIT",
   "description": "Internationalization (i18n) support for Object UI with 10+ language packs, RTL layout, and date/currency formatting.",
   "homepage": "https://www.objectui.org",
@@ -27,15 +28,15 @@
     }
   },
   "dependencies": {
-    "i18next": "^25.8.4",
+    "i18next": "^25.8.7",
     "react-i18next": "^16.5.4"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "^19.1.8",
-    "react": "^19.1.0",
+    "@types/react": "19.2.13",
+    "react": "19.2.4",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },

package/src/__tests__/provider.test.tsx

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import React from 'react';
+import { I18nProvider, useObjectTranslation, useI18nContext } from '../provider';
+import { createI18n } from '../i18n';
+
+describe('I18nProvider', () => {
+  it('creates i18n instance from config', () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(I18nProvider, { config: { defaultLanguage: 'en', detectBrowserLanguage: false } }, children);
+
+    const { result } = renderHook(() => useObjectTranslation(), { wrapper });
+
+    expect(result.current.i18n).toBeDefined();
+    expect(result.current.language).toBe('en');
+  });
+
+  it('accepts pre-created instance', () => {
+    const instance = createI18n({ defaultLanguage: 'fr', detectBrowserLanguage: false });
+
+    const wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(I18nProvider, { instance }, children);
+
+    const { result } = renderHook(() => useObjectTranslation(), { wrapper });
+
+    expect(result.current.i18n).toBeDefined();
+    expect(result.current.language).toBe('fr');
+  });
+});
+
+describe('useObjectTranslation', () => {
+  const wrapper = ({ children }: { children: React.ReactNode }) =>
+    React.createElement(I18nProvider, { config: { defaultLanguage: 'en', detectBrowserLanguage: false } }, children);
+
+  it('returns t, language, changeLanguage, direction, i18n', () => {
+    const { result } = renderHook(() => useObjectTranslation(), { wrapper });
+
+    expect(result.current.t).toBeTypeOf('function');
+    expect(result.current.language).toBeTypeOf('string');
+    expect(result.current.changeLanguage).toBeTypeOf('function');
+    expect(result.current.direction).toBeTypeOf('string');
+    expect(result.current.i18n).toBeDefined();
+  });
+
+  it('translates keys correctly', () => {
+    const { result } = renderHook(() => useObjectTranslation(), { wrapper });
+
+    expect(result.current.t('common.save')).toBe('Save');
+    expect(result.current.t('common.cancel')).toBe('Cancel');
+    expect(result.current.t('common.delete')).toBe('Delete');
+  });
+
+  it('returns en as default language', () => {
+    const { result } = renderHook(() => useObjectTranslation(), { wrapper });
+
+    expect(result.current.language).toBe('en');
+  });
+
+  it('works with Chinese language', () => {
+    const zhWrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(I18nProvider, { config: { defaultLanguage: 'zh', detectBrowserLanguage: false } }, children);
+
+    const { result } = renderHook(() => useObjectTranslation(), { wrapper: zhWrapper });
+
+    expect(result.current.language).toBe('zh');
+    expect(result.current.t('common.save')).toBe('保存');
+    expect(result.current.t('common.cancel')).toBe('取消');
+  });
+
+  it('changeLanguage updates language', async () => {
+    const { result } = renderHook(() => useObjectTranslation(), { wrapper });
+
+    expect(result.current.language).toBe('en');
+
+    await act(async () => {
+      await result.current.changeLanguage('zh');
+    });
+
+    await waitFor(() => {
+      expect(result.current.language).toBe('zh');
+    });
+  });
+
+  it('returns RTL direction for Arabic', () => {
+    const arWrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(I18nProvider, { config: { defaultLanguage: 'ar', detectBrowserLanguage: false } }, children);
+
+    const { result } = renderHook(() => useObjectTranslation(), { wrapper: arWrapper });
+
+    expect(result.current.direction).toBe('rtl');
+  });
+});
+
+describe('useI18nContext', () => {
+  it('throws when used outside provider', () => {
+    // Suppress console.error from React for the expected error
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => {
+      renderHook(() => useI18nContext());
+    }).toThrow('useI18nContext must be used within an I18nProvider');
+
+    spy.mockRestore();
+  });
+
+  it('returns context inside provider', () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(I18nProvider, { config: { defaultLanguage: 'en', detectBrowserLanguage: false } }, children);
+
+    const { result } = renderHook(() => useI18nContext(), { wrapper });
+
+    expect(result.current.language).toBe('en');
+    expect(result.current.changeLanguage).toBeTypeOf('function');
+    expect(result.current.direction).toBe('ltr');
+    expect(result.current.i18n).toBeDefined();
+  });
+});