@object-ui/i18n 0.5.0

package/dist/provider.js

@@ -0,0 +1,84 @@
+/**
+ * @object-ui/i18n - React integration
+ *
+ * Provides I18nProvider and useObjectTranslation hook for React components.
+ */
+import React, { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { I18nextProvider, useTranslation } from 'react-i18next';
+import { createI18n, getDirection } from './i18n';
+const ObjectI18nContext = createContext(null);
+/**
+ * I18nProvider - Wraps your app with i18n support
+ *
+ * @example
+ * ```tsx
+ * <I18nProvider config={{ defaultLanguage: 'zh' }}>
+ *   <App />
+ * </I18nProvider>
+ * ```
+ */
+export function I18nProvider({ config, instance: externalInstance, children }) {
+    const i18nInstance = useMemo(() => externalInstance || createI18n(config), [externalInstance]);
+    const [language, setLanguage] = useState(i18nInstance.language || 'en');
+    const direction = getDirection(language);
+    useEffect(() => {
+        const handleLanguageChanged = (lng) => {
+            setLanguage(lng);
+            // Update document direction for RTL support
+            if (typeof document !== 'undefined') {
+                document.documentElement.dir = getDirection(lng);
+                document.documentElement.lang = lng;
+            }
+        };
+        i18nInstance.on('languageChanged', handleLanguageChanged);
+        return () => {
+            i18nInstance.off('languageChanged', handleLanguageChanged);
+        };
+    }, [i18nInstance]);
+    const contextValue = useMemo(() => ({
+        language,
+        changeLanguage: async (lang) => {
+            await i18nInstance.changeLanguage(lang);
+        },
+        direction,
+        i18n: i18nInstance,
+    }), [language, direction, i18nInstance]);
+    return React.createElement(ObjectI18nContext.Provider, { value: contextValue }, React.createElement(I18nextProvider, { i18n: i18nInstance }, children));
+}
+/**
+ * Hook to access Object UI i18n context
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { t, language, changeLanguage, direction } = useObjectTranslation();
+ *   return <div dir={direction}>{t('common.save')}</div>;
+ * }
+ * ```
+ */
+export function useObjectTranslation(ns) {
+    const context = useContext(ObjectI18nContext);
+    const { t, i18n } = useTranslation(ns);
+    return {
+        /** Translation function */
+        t,
+        /** Current language code */
+        language: context?.language || i18n.language || 'en',
+        /** Change the active language */
+        changeLanguage: context?.changeLanguage || (async (lang) => { await i18n.changeLanguage(lang); }),
+        /** Current text direction */
+        direction: context?.direction || 'ltr',
+        /** The underlying i18next instance */
+        i18n,
+    };
+}
+/**
+ * Hook to access the i18n context directly
+ */
+export function useI18nContext() {
+    const context = useContext(ObjectI18nContext);
+    if (!context) {
+        throw new Error('useI18nContext must be used within an I18nProvider');
+    }
+    return context;
+}

package/dist/utils/formatting.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @object-ui/i18n - Date and currency formatting utilities
+ *
+ * Uses the native Intl API for locale-aware formatting.
+ */
+export interface DateFormatOptions {
+    locale?: string;
+    style?: 'short' | 'medium' | 'long' | 'full';
+    dateStyle?: Intl.DateTimeFormatOptions['dateStyle'];
+    timeStyle?: Intl.DateTimeFormatOptions['timeStyle'];
+}
+export interface CurrencyFormatOptions {
+    locale?: string;
+    currency?: string;
+    style?: 'currency' | 'decimal' | 'percent';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+export interface NumberFormatOptions {
+    locale?: string;
+    style?: 'decimal' | 'percent' | 'unit';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    notation?: 'standard' | 'scientific' | 'engineering' | 'compact';
+}
+/**
+ * Format a date according to locale conventions
+ */
+export declare function formatDate(date: Date | string | number, options?: DateFormatOptions): string;
+/**
+ * Format a date and time according to locale conventions
+ */
+export declare function formatDateTime(date: Date | string | number, options?: DateFormatOptions): string;
+/**
+ * Format a relative time (e.g., "2 days ago", "in 3 hours")
+ */
+export declare function formatRelativeTime(date: Date | string | number, locale?: string): string;
+/**
+ * Format a currency value according to locale conventions
+ */
+export declare function formatCurrency(value: number, options?: CurrencyFormatOptions): string;
+/**
+ * Format a number according to locale conventions
+ */
+export declare function formatNumber(value: number, options?: NumberFormatOptions): string;

package/dist/utils/formatting.js

@@ -0,0 +1,86 @@
+/**
+ * @object-ui/i18n - Date and currency formatting utilities
+ *
+ * Uses the native Intl API for locale-aware formatting.
+ */
+/**
+ * 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);
+    if (isNaN(d.getTime())) {
+        return String(date);
+    }
+    const styleMap = {
+        short: { year: '2-digit', month: 'numeric', day: 'numeric' },
+        medium: { year: 'numeric', month: 'short', day: 'numeric' },
+        long: { year: 'numeric', month: 'long', day: 'numeric' },
+        full: { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' },
+    };
+    const formatOptions = options.dateStyle
+        ? { dateStyle: options.dateStyle, timeStyle: options.timeStyle }
+        : styleMap[style] || styleMap.medium;
+    return new Intl.DateTimeFormat(locale, formatOptions).format(d);
+}
+/**
+ * Format a date and time according to locale conventions
+ */
+export function formatDateTime(date, options = {}) {
+    const { locale = 'en', style = 'medium' } = options;
+    const d = date instanceof Date ? date : new Date(date);
+    if (isNaN(d.getTime())) {
+        return String(date);
+    }
+    const styleMap = {
+        short: { year: '2-digit', month: 'numeric', day: 'numeric', hour: 'numeric', minute: 'numeric' },
+        medium: { year: 'numeric', month: 'short', day: 'numeric', hour: 'numeric', minute: 'numeric' },
+        long: { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', second: 'numeric' },
+        full: { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', second: 'numeric', timeZoneName: 'short' },
+    };
+    return new Intl.DateTimeFormat(locale, styleMap[style] || styleMap.medium).format(d);
+}
+/**
+ * Format a relative time (e.g., "2 days ago", "in 3 hours")
+ */
+export function formatRelativeTime(date, locale = 'en') {
+    const d = date instanceof Date ? date : new Date(date);
+    const now = new Date();
+    const diffMs = d.getTime() - now.getTime();
+    const diffSec = Math.round(diffMs / 1000);
+    const diffMin = Math.round(diffSec / 60);
+    const diffHour = Math.round(diffMin / 60);
+    const diffDay = Math.round(diffHour / 24);
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+    if (Math.abs(diffSec) < 60)
+        return rtf.format(diffSec, 'second');
+    if (Math.abs(diffMin) < 60)
+        return rtf.format(diffMin, 'minute');
+    if (Math.abs(diffHour) < 24)
+        return rtf.format(diffHour, 'hour');
+    if (Math.abs(diffDay) < 30)
+        return rtf.format(diffDay, 'day');
+    const diffMonth = Math.round(diffDay / 30);
+    if (Math.abs(diffMonth) < 12)
+        return rtf.format(diffMonth, 'month');
+    return rtf.format(Math.round(diffDay / 365), 'year');
+}
+/**
+ * Format a currency value according to locale conventions
+ */
+export function formatCurrency(value, options = {}) {
+    const { locale = 'en', currency = 'USD', minimumFractionDigits, maximumFractionDigits } = options;
+    return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+        minimumFractionDigits,
+        maximumFractionDigits,
+    }).format(value);
+}
+/**
+ * Format a number according to locale conventions
+ */
+export function formatNumber(value, options = {}) {
+    const { locale = 'en', ...rest } = options;
+    return new Intl.NumberFormat(locale, rest).format(value);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from './formatting';

package/dist/utils/index.js

@@ -0,0 +1 @@
+export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from './formatting';

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@object-ui/i18n",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Internationalization (i18n) support for Object UI with 10+ language packs, RTL layout, and date/currency formatting.",
+  "homepage": "https://www.objectui.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/objectui.git",
+    "directory": "packages/i18n"
+  },
+  "bugs": {
+    "url": "https://github.com/objectstack-ai/objectui/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./locales/*": {
+      "types": "./dist/locales/*.d.ts",
+      "import": "./dist/locales/*.js"
+    }
+  },
+  "dependencies": {
+    "i18next": "^25.8.4",
+    "react-i18next": "^16.5.4"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "react": "^19.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}

package/src/__tests__/i18n.test.ts

@@ -0,0 +1,228 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  createI18n,
+  getDirection,
+  getAvailableLanguages,
+  builtInLocales,
+  isRTL,
+  RTL_LANGUAGES,
+  formatDate,
+  formatDateTime,
+  formatCurrency,
+  formatNumber,
+} from '../index';
+
+describe('@object-ui/i18n', () => {
+  describe('createI18n', () => {
+    it('creates an i18next instance with default config', () => {
+      const i18n = createI18n({ detectBrowserLanguage: false });
+      expect(i18n).toBeDefined();
+      expect(i18n.language).toBe('en');
+    });
+
+    it('creates an instance with specified default language', () => {
+      const i18n = createI18n({ defaultLanguage: 'zh', detectBrowserLanguage: false });
+      expect(i18n.language).toBe('zh');
+    });
+
+    it('loads all built-in locales', () => {
+      const i18n = createI18n({ detectBrowserLanguage: false });
+      const langs = getAvailableLanguages(i18n);
+      expect(langs).toContain('en');
+      expect(langs).toContain('zh');
+      expect(langs).toContain('ja');
+      expect(langs).toContain('ko');
+      expect(langs).toContain('de');
+      expect(langs).toContain('fr');
+      expect(langs).toContain('es');
+      expect(langs).toContain('pt');
+      expect(langs).toContain('ru');
+      expect(langs).toContain('ar');
+      expect(langs.length).toBeGreaterThanOrEqual(10);
+    });
+
+    it('translates common keys in English', () => {
+      const i18n = createI18n({ defaultLanguage: 'en', detectBrowserLanguage: false });
+      expect(i18n.t('common.save')).toBe('Save');
+      expect(i18n.t('common.cancel')).toBe('Cancel');
+      expect(i18n.t('common.delete')).toBe('Delete');
+      expect(i18n.t('common.loading')).toBe('Loading...');
+    });
+
+    it('translates common keys in Chinese', () => {
+      const i18n = createI18n({ defaultLanguage: 'zh', detectBrowserLanguage: false });
+      expect(i18n.t('common.save')).toBe('保存');
+      expect(i18n.t('common.cancel')).toBe('取消');
+      expect(i18n.t('common.delete')).toBe('删除');
+      expect(i18n.t('common.loading')).toBe('加载中...');
+    });
+
+    it('translates common keys in Japanese', () => {
+      const i18n = createI18n({ defaultLanguage: 'ja', detectBrowserLanguage: false });
+      expect(i18n.t('common.save')).toBe('保存');
+      expect(i18n.t('common.cancel')).toBe('キャンセル');
+    });
+
+    it('translates common keys in Korean', () => {
+      const i18n = createI18n({ defaultLanguage: 'ko', detectBrowserLanguage: false });
+      expect(i18n.t('common.save')).toBe('저장');
+      expect(i18n.t('common.cancel')).toBe('취소');
+    });
+
+    it('supports interpolation in validation messages', () => {
+      const i18n = createI18n({ defaultLanguage: 'en', detectBrowserLanguage: false });
+      expect(i18n.t('validation.required', { field: 'Name' })).toBe('Name is required');
+      expect(i18n.t('validation.minLength', { field: 'Password', min: 8 })).toBe(
+        'Password must be at least 8 characters',
+      );
+    });
+
+    it('supports interpolation in Chinese', () => {
+      const i18n = createI18n({ defaultLanguage: 'zh', detectBrowserLanguage: false });
+      expect(i18n.t('validation.required', { field: '姓名' })).toBe('姓名不能为空');
+    });
+
+    it('falls back to English for unknown language', () => {
+      const i18n = createI18n({ defaultLanguage: 'xx', fallbackLanguage: 'en', detectBrowserLanguage: false });
+      expect(i18n.t('common.save')).toBe('Save');
+    });
+
+    it('merges custom resources with built-in locales', () => {
+      const i18n = createI18n({
+        defaultLanguage: 'en',
+        detectBrowserLanguage: false,
+        resources: {
+          en: { custom: { greeting: 'Hello!' } },
+        },
+      });
+      expect(i18n.t('custom.greeting')).toBe('Hello!');
+      // Built-in translations still work
+      expect(i18n.t('common.save')).toBe('Save');
+    });
+
+    it('changes language dynamically', async () => {
+      const i18n = createI18n({ defaultLanguage: 'en', detectBrowserLanguage: false });
+      expect(i18n.t('common.save')).toBe('Save');
+
+      await i18n.changeLanguage('zh');
+      expect(i18n.language).toBe('zh');
+      expect(i18n.t('common.save')).toBe('保存');
+
+      await i18n.changeLanguage('ja');
+      expect(i18n.language).toBe('ja');
+      expect(i18n.t('common.save')).toBe('保存');
+    });
+  });
+
+  describe('getDirection', () => {
+    it('returns ltr for English', () => {
+      expect(getDirection('en')).toBe('ltr');
+    });
+
+    it('returns ltr for Chinese', () => {
+      expect(getDirection('zh')).toBe('ltr');
+    });
+
+    it('returns rtl for Arabic', () => {
+      expect(getDirection('ar')).toBe('rtl');
+    });
+
+    it('returns ltr for unknown languages', () => {
+      expect(getDirection('xx')).toBe('ltr');
+    });
+  });
+
+  describe('isRTL', () => {
+    it('returns true for Arabic', () => {
+      expect(isRTL('ar')).toBe(true);
+    });
+
+    it('returns false for English', () => {
+      expect(isRTL('en')).toBe(false);
+    });
+
+    it('returns false for Chinese', () => {
+      expect(isRTL('zh')).toBe(false);
+    });
+  });
+
+  describe('RTL_LANGUAGES', () => {
+    it('includes Arabic', () => {
+      expect(RTL_LANGUAGES).toContain('ar');
+    });
+
+    it('includes Hebrew', () => {
+      expect(RTL_LANGUAGES).toContain('he');
+    });
+  });
+
+  describe('builtInLocales', () => {
+    it('has 10 built-in language packs', () => {
+      expect(Object.keys(builtInLocales).length).toBe(10);
+    });
+
+    it('all locales have the same top-level keys', () => {
+      const enKeys = Object.keys(builtInLocales.en).sort();
+      for (const [lang, locale] of Object.entries(builtInLocales)) {
+        const keys = Object.keys(locale).sort();
+        expect(keys).toEqual(enKeys);
+      }
+    });
+
+    it('all locales have common section keys matching English', () => {
+      const enCommonKeys = Object.keys(builtInLocales.en.common).sort();
+      for (const [lang, locale] of Object.entries(builtInLocales)) {
+        const keys = Object.keys(locale.common).sort();
+        expect(keys).toEqual(enCommonKeys);
+      }
+    });
+  });
+
+  describe('formatDate', () => {
+    it('formats a date with default options', () => {
+      const result = formatDate(new Date(2026, 0, 15), { locale: 'en' });
+      expect(result).toContain('Jan');
+      expect(result).toContain('15');
+      expect(result).toContain('2026');
+    });
+
+    it('formats a date with short style', () => {
+      const result = formatDate(new Date(2026, 0, 15), { locale: 'en', style: 'short' });
+      expect(result).toContain('15');
+    });
+
+    it('returns string for invalid dates', () => {
+      const result = formatDate('invalid-date');
+      expect(result).toBe('invalid-date');
+    });
+  });
+
+  describe('formatCurrency', () => {
+    it('formats USD by default', () => {
+      const result = formatCurrency(1234.56, { locale: 'en' });
+      expect(result).toContain('1,234.56');
+    });
+
+    it('formats EUR', () => {
+      const result = formatCurrency(1234.56, { locale: 'de', currency: 'EUR' });
+      expect(result).toContain('1.234,56');
+    });
+
+    it('formats CNY', () => {
+      const result = formatCurrency(1234.56, { locale: 'zh', currency: 'CNY' });
+      expect(result).toContain('1,234.56');
+    });
+  });
+
+  describe('formatNumber', () => {
+    it('formats a number with default locale', () => {
+      const result = formatNumber(1234567.89, { locale: 'en' });
+      expect(result).toContain('1,234,567.89');
+    });
+
+    it('formats with compact notation', () => {
+      const result = formatNumber(1234567, { locale: 'en', notation: 'compact' });
+      expect(result).toContain('M'); // e.g. 1.2M
+    });
+  });
+});

package/src/i18n.ts

@@ -0,0 +1,98 @@
+/**
+ * @object-ui/i18n - Core i18n configuration and initialization
+ *
+ * Wraps i18next with Object UI defaults and built-in locale support.
+ */
+import i18next, { type i18n as I18nInstance } from 'i18next';
+import { builtInLocales, isRTL } from './locales/index';
+import type { TranslationKeys } from './locales/en';
+
+export interface I18nConfig {
+  /** Default language (default: 'en') */
+  defaultLanguage?: string;
+  /** Fallback language (default: 'en') */
+  fallbackLanguage?: string;
+  /** Additional translation resources to merge with built-in locales */
+  resources?: Record<string, Record<string, unknown>>;
+  /** Whether to detect browser language automatically (default: true) */
+  detectBrowserLanguage?: boolean;
+  /** i18next interpolation options */
+  interpolation?: {
+    escapeValue?: boolean;
+    prefix?: string;
+    suffix?: string;
+  };
+}
+
+/**
+ * Create and initialize an i18next instance with Object UI defaults
+ */
+export function createI18n(config: I18nConfig = {}): I18nInstance {
+  const {
+    defaultLanguage = 'en',
+    fallbackLanguage = 'en',
+    resources = {},
+    detectBrowserLanguage = true,
+    interpolation,
+  } = config;
+
+  // Merge built-in locales with user-provided resources
+  const mergedResources: Record<string, { translation: Record<string, unknown> }> = {};
+
+  for (const [lang, translations] of Object.entries(builtInLocales)) {
+    mergedResources[lang] = {
+      translation: {
+        ...translations,
+        ...(resources[lang] || {}),
+      },
+    };
+  }
+
+  // Add any additional languages from resources not in built-in locales
+  for (const [lang, translations] of Object.entries(resources)) {
+    if (!mergedResources[lang]) {
+      mergedResources[lang] = { translation: translations as Record<string, unknown> };
+    }
+  }
+
+  // Detect browser language if enabled
+  let lng = defaultLanguage;
+  if (detectBrowserLanguage && typeof navigator !== 'undefined') {
+    const browserLang = navigator.language?.split('-')[0];
+    if (browserLang && mergedResources[browserLang]) {
+      lng = browserLang;
+    }
+  }
+
+  const instance = i18next.createInstance();
+
+  instance.init({
+    lng,
+    fallbackLng: fallbackLanguage,
+    resources: mergedResources,
+    interpolation: {
+      escapeValue: false, // React already escapes
+      ...interpolation,
+    },
+    returnNull: false,
+  });
+
+  return instance;
+}
+
+/**
+ * Get the text direction for the current language
+ */
+export function getDirection(lang: string): 'ltr' | 'rtl' {
+  return isRTL(lang) ? 'rtl' : 'ltr';
+}
+
+/**
+ * Get available languages from an i18n instance
+ */
+export function getAvailableLanguages(instance: I18nInstance): string[] {
+  const resources = instance.options.resources;
+  return resources ? Object.keys(resources) : [];
+}
+
+export type { TranslationKeys };

package/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * @object-ui/i18n
+ *
+ * Internationalization (i18n) support for Object UI.
+ * Provides 10+ built-in language packs, RTL support, and date/currency formatting.
+ *
+ * @example
+ * ```tsx
+ * import { I18nProvider, useObjectTranslation } from '@object-ui/i18n';
+ *
+ * function App() {
+ *   return (
+ *     <I18nProvider config={{ defaultLanguage: 'zh' }}>
+ *       <MyComponent />
+ *     </I18nProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const { t, language, changeLanguage, direction } = useObjectTranslation();
+ *   return (
+ *     <div dir={direction}>
+ *       <h1>{t('common.save')}</h1>
+ *       <button onClick={() => changeLanguage('en')}>English</button>
+ *       <button onClick={() => changeLanguage('zh')}>中文</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Core i18n setup
+export { createI18n, getDirection, getAvailableLanguages, type I18nConfig, type TranslationKeys } from './i18n';
+
+// React integration
+export { I18nProvider, useObjectTranslation, useI18nContext, type I18nProviderProps } from './provider';
+
+// Locale packs
+export { builtInLocales, isRTL, RTL_LANGUAGES } from './locales/index';
+export { default as en } from './locales/en';
+export { default as zh } from './locales/zh';
+export { default as ja } from './locales/ja';
+export { default as ko } from './locales/ko';
+export { default as de } from './locales/de';
+export { default as fr } from './locales/fr';
+export { default as es } from './locales/es';
+export { default as pt } from './locales/pt';
+export { default as ru } from './locales/ru';
+export { default as ar } from './locales/ar';
+
+// Formatting utilities
+export {
+  formatDate,
+  formatDateTime,
+  formatRelativeTime,
+  formatCurrency,
+  formatNumber,
+  type DateFormatOptions,
+  type CurrencyFormatOptions,
+  type NumberFormatOptions,
+} from './utils/index';