@umituz/react-native-localization 2.2.2 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-localization",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "description": "English-only localization system for React Native apps with i18n support",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/infrastructure/config/I18nInitializer.ts

@@ -1,117 +1,120 @@
 /**
  * i18n Initializer
  *
- * Handles i18n configuration and initialization
- * - Auto-discovers project translations
- * - i18n setup
- * - React i18next integration
+ * Handles i18n configuration with namespace support
+ * - Loads package translations
+ * - Loads app translations (merges with package)
+ * - Namespace-based organization (common, auth, etc.)
  */
 
 import i18n from 'i18next';
 import { initReactI18next } from 'react-i18next';
-import { DEFAULT_LANGUAGE, SUPPORTED_LANGUAGES } from './languages';
+import { DEFAULT_LANGUAGE } from './languages';
 import { TranslationLoader } from './TranslationLoader';
 
+const DEFAULT_NAMESPACE = 'common';
+
 export class I18nInitializer {
   private static reactI18nextInitialized = false;
 
   /**
-   * Auto-discover project translations from common paths
+   * Build resources with package + app translations merged
    */
-  private static loadProjectTranslations(): Record<string, any> {
-    const possiblePaths = [
-      './src/locales/en-US',           // App structure
-      './locales/en-US',               // Alternative app structure
-      '../src/locales/en-US',          // Relative from package
-    ];
-
-    for (const path of possiblePaths) {
-      try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const translations = require(path);
-        return translations.default || translations;
-      } catch {
-        // Try next path
+  private static buildResources(): Record<string, Record<string, any>> {
+    const packageTranslations = TranslationLoader.loadPackageTranslations();
+    const appTranslations = TranslationLoader.loadAppTranslations();
+
+    const resources: Record<string, Record<string, any>> = {
+      'en-US': {},
+    };
+
+    const enUSPackage = packageTranslations['en-US'] || {};
+
+    // Add package namespaces
+    for (const [namespace, translations] of Object.entries(enUSPackage)) {
+      resources['en-US'][namespace] = translations;
+    }
+
+    // Merge app namespaces (app overrides package)
+    for (const [namespace, translations] of Object.entries(appTranslations)) {
+      if (resources['en-US'][namespace]) {
+        resources['en-US'][namespace] = TranslationLoader.mergeTranslations(
+          resources['en-US'][namespace],
+          translations
+        );
+      } else {
+        resources['en-US'][namespace] = translations;
       }
     }
 
-    return {};
+    return resources;
   }
 
-  /**
-   * Build resources object for all supported languages
-   */
-  private static buildResources(): Record<string, { translation: any }> {
-    const resources: Record<string, { translation: any }> = {};
+  private static getNamespaces(): string[] {
     const packageTranslations = TranslationLoader.loadPackageTranslations();
-    const projectTranslations = this.loadProjectTranslations();
-
-    // For en-US, merge package and project translations
-    resources['en-US'] = {
-      translation: TranslationLoader.mergeTranslations(
-        packageTranslations['en-US'] || {},
-        projectTranslations
-      ),
-    };
+    const appTranslations = TranslationLoader.loadAppTranslations();
 
-    return resources;
+    const enUSPackage = packageTranslations['en-US'] || {};
+    const namespaces = new Set([
+      ...Object.keys(enUSPackage),
+      ...Object.keys(appTranslations),
+    ]);
+
+    if (!namespaces.has(DEFAULT_NAMESPACE)) {
+      namespaces.add(DEFAULT_NAMESPACE);
+    }
+
+    return Array.from(namespaces);
   }
 
-  /**
-   * Initialize i18next
-   */
   static initialize(): void {
-    // Prevent multiple initializations
     if (i18n.isInitialized) {
       return;
     }
 
     try {
-      // Use initReactI18next once
       if (!this.reactI18nextInitialized) {
         i18n.use(initReactI18next);
         this.reactI18nextInitialized = true;
       }
 
       const resources = this.buildResources();
+      const namespaces = this.getNamespaces();
 
       i18n.init({
         resources,
         lng: DEFAULT_LANGUAGE,
         fallbackLng: DEFAULT_LANGUAGE,
-
-        interpolation: {
-          escapeValue: false, // React already escapes values
-        },
-
-        react: {
-          useSuspense: false, // Disable suspense for React Native
-        },
-
-        compatibilityJSON: 'v3', // Use v3 format for React Native
-        pluralSeparator: '_', // Use underscore separator for plural keys
-        keySeparator: '.', // Use dot separator for nested keys
-
-        debug: typeof __DEV__ !== 'undefined' && __DEV__,
+        ns: namespaces,
+        defaultNS: DEFAULT_NAMESPACE,
+        fallbackNS: DEFAULT_NAMESPACE,
+        interpolation: { escapeValue: false },
+        react: { useSuspense: false },
+        compatibilityJSON: 'v3',
+        pluralSeparator: '_',
+        keySeparator: '.',
+        nsSeparator: ':',
+        saveMissing: false,
+        missingKeyHandler: false,
+        debug: false,
       });
-
     } catch (error) {
-      // Don't throw - allow app to continue without i18n
       if (typeof __DEV__ !== 'undefined' && __DEV__) {
-        console.error('❌ i18n initialization error:', error);
+        console.error('[Localization] init error:', error);
       }
     }
   }
 
   /**
-   * Add additional translation resources
+   * Add translation resources at runtime
    */
-  static addTranslationResources(resources: Record<string, { translation: any }>): void {
-    for (const [langCode, resource] of Object.entries(resources)) {
-      if (resource.translation) {
-        const existingTranslations = i18n.getResourceBundle(langCode, 'translation') || {};
-        const mergedTranslations = { ...existingTranslations, ...resource.translation };
-        i18n.addResourceBundle(langCode, 'translation', mergedTranslations, true, true);
+  static addTranslationResources(
+    languageCode: string,
+    namespaceResources: Record<string, any>
+  ): void {
+    for (const [namespace, translations] of Object.entries(namespaceResources)) {
+      if (translations && typeof translations === 'object') {
+        i18n.addResourceBundle(languageCode, namespace, translations, true, true);
       }
     }
   }

package/src/infrastructure/config/TranslationLoader.ts

@@ -1,58 +1,73 @@
 /**
  * Translation Loader
  *
- * Handles loading of translations from package only
+ * Loads translations from package and app
  */
 
 export class TranslationLoader {
   /**
-   * Load package translations (en-US only)
+   * Load package translations (en-US)
    */
   static loadPackageTranslations(): Record<string, any> {
     try {
       // eslint-disable-next-line @typescript-eslint/no-require-imports
       const translations = require('../locales/en-US');
       return { 'en-US': translations.default || translations };
-    } catch (error) {
+    } catch {
       return { 'en-US': {} };
     }
   }
 
   /**
-   * Merge package defaults with project-specific translations
+   * Load app translations from common paths
    */
-  static mergeTranslations(
-    packageTranslations: any,
-    projectTranslations: any
-  ): any {
-    if (!projectTranslations || Object.keys(projectTranslations).length === 0) {
-      return packageTranslations;
+  static loadAppTranslations(): Record<string, any> {
+    const paths = [
+      '@/domains/localization/infrastructure/locales/en-US',
+      './src/domains/localization/infrastructure/locales/en-US',
+      '../../../src/domains/localization/infrastructure/locales/en-US',
+    ];
+
+    for (const path of paths) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const translations = require(path);
+        return translations.default || translations;
+      } catch {
+        continue;
+      }
+    }
+
+    return {};
+  }
+
+  /**
+   * Deep merge translations (app overrides package)
+   */
+  static mergeTranslations(base: any, override: any): any {
+    if (!override || Object.keys(override).length === 0) {
+      return base;
     }
 
-    const merged = { ...packageTranslations };
-
-    for (const key in projectTranslations) {
-      if (projectTranslations.hasOwnProperty(key)) {
-        if (
-          typeof projectTranslations[key] === 'object' &&
-          projectTranslations[key] !== null &&
-          !Array.isArray(projectTranslations[key]) &&
-          typeof packageTranslations[key] === 'object' &&
-          packageTranslations[key] !== null &&
-          !Array.isArray(packageTranslations[key])
-        ) {
-          // Deep merge nested objects
-          merged[key] = this.mergeTranslations(
-            packageTranslations[key],
-            projectTranslations[key]
-          );
+    const merged = { ...base };
+
+    for (const key in override) {
+      if (Object.prototype.hasOwnProperty.call(override, key)) {
+        const baseVal = base[key];
+        const overrideVal = override[key];
+
+        if (this.isObject(baseVal) && this.isObject(overrideVal)) {
+          merged[key] = this.mergeTranslations(baseVal, overrideVal);
         } else {
-          // Override with project translation
-          merged[key] = projectTranslations[key];
+          merged[key] = overrideVal;
         }
       }
     }
 
     return merged;
   }
+
+  private static isObject(val: any): boolean {
+    return val !== null && typeof val === 'object' && !Array.isArray(val);
+  }
 }

package/src/infrastructure/config/i18n.ts

@@ -1,15 +1,14 @@
 /**
  * i18n Configuration
  *
- * Auto-initializes i18n with project translations
+ * Auto-initializes i18n with namespace support
+ * Usage: t('namespace:key') e.g., t('common:cancel')
  */
 
 import { I18nInitializer } from './I18nInitializer';
 import i18n from 'i18next';
 
-// Initialize i18n automatically
 I18nInitializer.initialize();
 
-// Export for advanced usage
 export const addTranslationResources = I18nInitializer.addTranslationResources;
 export default i18n;

package/src/infrastructure/hooks/useTranslation.ts

@@ -14,55 +14,6 @@ import i18n from '../config/i18n';
  * Hook for translation functionality
  */
 export const useTranslationFunction = (): ((key: string, options?: any) => string) => {
-  // Ensure settings translations are loaded
-  if (i18n.isInitialized && typeof i18n.t === 'function') {
-    const existingTranslations = i18n.getResourceBundle('en-US', 'translation') || {};
-
-    // Check if settings translations are missing
-    if (!existingTranslations.settings) {
-      // Add settings translations as fallback
-      const settingsTranslations = {
-        settings: {
-          editProfile: "Edit Profile",
-          sections: {
-            physicalInfoAndGoals: "Physical Info and Goals",
-            appSettings: "App Settings",
-            accountManagement: "Account Management"
-          },
-          personalInfo: {
-            title: "Personal Information",
-            subtitle: "Height, Weight, Age, Gender"
-          },
-          nutritionGoals: {
-            title: "Nutrition Goals",
-            subtitle: "Calories, Protein, Carbs, Fat"
-          },
-          notifications: {
-            title: "Notification Preferences",
-            subtitle: "Water and meal reminders"
-          },
-          darkMode: {
-            title: "Dark Mode",
-            subtitle: "Change app theme"
-          },
-          passwordChange: {
-            title: "Change Password"
-          },
-          saveChanges: "Save Changes",
-          logout: "Logout",
-          emptyState: {
-            title: "No recipes yet",
-            subtitle: "Create your first recipe to get started"
-          },
-          addToList: "Add to List"
-        }
-      };
-
-      const mergedTranslations = { ...existingTranslations, ...settingsTranslations };
-      i18n.addResourceBundle('en-US', 'translation', mergedTranslations, true, true);
-    }
-  }
-
   // Use direct i18n.t for reliability (no React context issues)
   return (key: string, options?: any): string => {
     if (i18n.isInitialized && typeof i18n.t === 'function') {

package/src/infrastructure/locales/en-US/common.json

@@ -0,0 +1,57 @@
+{
+  "cancel": "Cancel",
+  "confirm": "Confirm",
+  "continue": "Continue",
+  "delete": "Delete",
+  "edit": "Edit",
+  "error": "Error",
+  "loading": "Loading...",
+  "notNow": "Not Now",
+  "ok": "OK",
+  "optional": "Optional",
+  "save": "Save",
+  "somethingWentWrong": "Something went wrong",
+  "success": "Success",
+  "close": "Close",
+  "done": "Done",
+  "next": "Next",
+  "previous": "Previous",
+  "skip": "Skip",
+  "retry": "Retry",
+  "refresh": "Refresh",
+  "filter": "Filter",
+  "sort": "Sort",
+  "add": "Add",
+  "remove": "Remove",
+  "update": "Update",
+  "create": "Create",
+  "view": "View",
+  "details": "Details",
+  "share": "Share",
+  "download": "Download",
+  "upload": "Upload",
+  "submit": "Submit",
+  "reset": "Reset",
+  "clear": "Clear",
+  "apply": "Apply",
+  "yes": "Yes",
+  "no": "No",
+  "or": "or",
+  "all": "All",
+  "none": "None",
+  "of": "of",
+  "select": "Select",
+  "selected": "Selected",
+  "required": "Required",
+  "empty": "Empty",
+  "noData": "No data available",
+  "noResults": "No results found",
+  "tryAgain": "Try again",
+  "learnMore": "Learn more",
+  "getStarted": "Get started",
+  "viewAll": "View all",
+  "showMore": "Show more",
+  "showLess": "Show less",
+  "back": "Back",
+  "start": "Start"
+}

package/src/infrastructure/locales/en-US/index.ts

@@ -1,16 +1,19 @@
 /**
- * en-US Translation Module
+ * Translation loader for en-US with namespace support
  *
- * Direct loading for maximum compatibility across platforms
- * - Explicit imports for reliable bundling
- * - Flattened with dot notation
- * - Production-ready and tested
+ * Each JSON file represents a namespace that can be accessed via:
+ *   t('namespace:key') or t('namespace:nested.key')
+ *
+ * Example:
+ *   t('common:cancel') -> "Cancel"
+ *   t('auth:login.title') -> "Sign In"
  */
 
 import alerts from './alerts.json';
 import auth from './auth.json';
 import branding from './branding.json';
 import clipboard from './clipboard.json';
+import common from './common.json';
 import datetime from './datetime.json';
 import device from './device.json';
 import editor from './editor.json';
@@ -26,48 +29,26 @@ import settings from './settings.json';
 import sharing from './sharing.json';
 import templates from './templates.json';
 
-/**
- * Flatten nested objects with dot notation
- */
-const flattenObject = (
-  obj: Record<string, any>,
-  prefix = '',
-): Record<string, string> => {
-  const flattened: Record<string, string> = {};
-
-  Object.keys(obj).forEach((key) => {
-    const newKey = prefix ? `${prefix}.${key}` : key;
-
-    if (obj[key] && typeof obj[key] === 'object' && !Array.isArray(obj[key])) {
-      Object.assign(flattened, flattenObject(obj[key], newKey));
-    } else {
-      flattened[newKey] = obj[key];
-    }
-  });
-
-  return flattened;
-};
-
-// Create flattened translations object
 const translations = {
-  ...flattenObject(alerts, 'alerts'),
-  ...flattenObject(auth, 'auth'),
-  ...flattenObject(branding, 'branding'),
-  ...flattenObject(clipboard, 'clipboard'),
-  ...flattenObject(datetime, 'datetime'),
-  ...flattenObject(device, 'device'),
-  ...flattenObject(editor, 'editor'),
-  ...flattenObject(errors, 'errors'),
-  ...flattenObject(general, 'general'),
-  ...flattenObject(goals, 'goals'),
-  ...flattenObject(haptics, 'haptics'),
-  ...flattenObject(home, 'home'),
-  ...flattenObject(navigation, 'navigation'),
-  ...flattenObject(onboarding, 'onboarding'),
-  ...flattenObject(projects, 'projects'),
-  ...flattenObject(settings, 'settings'),
-  ...flattenObject(sharing, 'sharing'),
-  ...flattenObject(templates, 'templates'),
+  alerts,
+  auth,
+  branding,
+  clipboard,
+  common,
+  datetime,
+  device,
+  editor,
+  errors,
+  general,
+  goals,
+  haptics,
+  home,
+  navigation,
+  onboarding,
+  projects,
+  settings,
+  sharing,
+  templates,
 };
 
 export default translations;

package/src/infrastructure/storage/AsyncStorageWrapper.ts

@@ -1,9 +1,9 @@
 /**
- * AsyncStorage Wrapper
- * Simple wrapper for AsyncStorage operations
+ * Storage Wrapper
+ * Uses @umituz/react-native-storage for persistence
  */
 
-import AsyncStorage from '@react-native-async-storage/async-storage';
+import { storageRepository } from '@umituz/react-native-storage';
 
 export const STORAGE_KEYS = {
   LANGUAGE: '@localization:language',
@@ -11,19 +11,14 @@ export const STORAGE_KEYS = {
 
 export const StorageWrapper = {
   async getString(key: string, defaultValue: string): Promise<string> {
-    try {
-      const value = await AsyncStorage.getItem(key);
-      return value ?? defaultValue;
-    } catch (error) {
-      return defaultValue;
+    const result = await storageRepository.getString(key, defaultValue);
+    if (result.success && result.data !== null) {
+      return result.data;
     }
+    return defaultValue;
   },
 
   async setString(key: string, value: string): Promise<void> {
-    try {
-      await AsyncStorage.setItem(key, value);
-    } catch (error) {
-      // Ignore storage errors
-    }
+    await storageRepository.setString(key, value);
   },
 };

package/src/infrastructure/storage/LanguageInitializer.ts

@@ -7,58 +7,42 @@
  * - i18n setup
  */
 
-import AsyncStorage from '@react-native-async-storage/async-storage';
+import { storageRepository } from '@umituz/react-native-storage';
 import i18n from '../config/i18n';
 import { DEFAULT_LANGUAGE, getLanguageByCode, getDeviceLocale } from '../config/languages';
 
-// Storage key for language preference
 const LANGUAGE_STORAGE_KEY = '@localization:language';
 
 export class LanguageInitializer {
   /**
    * Initialize localization system
-   * Detects device locale and sets up i18n
    */
   static async initialize(): Promise<{
     languageCode: string;
     isRTL: boolean;
   }> {
     try {
-      // Get saved language preference
-      const savedLanguage = await AsyncStorage.getItem(LANGUAGE_STORAGE_KEY) || DEFAULT_LANGUAGE;
-
-      // Determine language code
+      const savedResult = await storageRepository.getString(LANGUAGE_STORAGE_KEY, DEFAULT_LANGUAGE);
+      const savedLanguage = savedResult.success && savedResult.data ? savedResult.data : DEFAULT_LANGUAGE;
       const languageCode = await this.determineLanguageCode(savedLanguage);
-
-      // Validate and get language object
       const finalLanguage = await this.validateAndSetupLanguage(languageCode);
 
       return finalLanguage;
     } catch (error) {
-      // Fallback to default language
       return await this.setupFallbackLanguage();
     }
   }
 
-  /**
-   * Determine which language code to use
-   */
   private static async determineLanguageCode(savedLanguage: string): Promise<string> {
     if (savedLanguage && savedLanguage !== DEFAULT_LANGUAGE) {
-      // User has previously selected a language
       return savedLanguage;
-    } else {
-      // First launch - detect device locale
-      const deviceLocale = getDeviceLocale();
-      // Save detected locale for future launches
-      await AsyncStorage.setItem(LANGUAGE_STORAGE_KEY, deviceLocale);
-      return deviceLocale;
     }
+
+    const deviceLocale = getDeviceLocale();
+    await storageRepository.setString(LANGUAGE_STORAGE_KEY, deviceLocale);
+    return deviceLocale;
   }
 
-  /**
-   * Validate language and set it up in i18n
-   */
   private static async validateAndSetupLanguage(languageCode: string): Promise<{
     languageCode: string;
     isRTL: boolean;
@@ -75,9 +59,6 @@ export class LanguageInitializer {
     };
   }
 
-  /**
-   * Set up fallback language when initialization fails
-   */
   private static async setupFallbackLanguage(): Promise<{
     languageCode: string;
     isRTL: boolean;

package/src/infrastructure/storage/LanguageSwitcher.ts

@@ -3,15 +3,13 @@
  *
  * Handles switching between languages
  * - Language validation
- * - Dynamic resource loading
  * - Persistence
  */
 
-import AsyncStorage from '@react-native-async-storage/async-storage';
+import { storageRepository } from '@umituz/react-native-storage';
 import i18n from '../config/i18n';
 import { getLanguageByCode } from '../config/languages';
 
-// Storage key for language preference
 const LANGUAGE_STORAGE_KEY = '@localization:language';
 
 export class LanguageSwitcher {
@@ -24,60 +22,16 @@ export class LanguageSwitcher {
   }> {
     const language = getLanguageByCode(languageCode);
 
-    // Validate language exists
     if (!language) {
       throw new Error(`Unsupported language: ${languageCode}`);
     }
 
-    // Load language resources if needed
-    await this.loadLanguageResources(languageCode);
-
-    // Update i18n
     await i18n.changeLanguage(languageCode);
-
-    // Persist language preference
-    await AsyncStorage.setItem(LANGUAGE_STORAGE_KEY, languageCode);
+    await storageRepository.setString(LANGUAGE_STORAGE_KEY, languageCode);
 
     return {
       languageCode,
       isRTL: language.rtl || false,
     };
   }
-
-  /**
-   * Load language resources dynamically
-   */
-  private static async loadLanguageResources(languageCode: string): Promise<void> {
-    if (i18n.hasResourceBundle(languageCode, 'translation')) {
-      return; // Already loaded
-    }
-
-    try {
-      // Try to load project translations from common paths
-      let translations: any = null;
-
-      const loadPaths = [
-        `../../../../../../src/domains/localization/infrastructure/locales/${languageCode}`,
-        `../../../../../../domains/localization/infrastructure/locales/${languageCode}`,
-        `../../../../../../src/locales/${languageCode}`,
-      ];
-
-      for (const path of loadPaths) {
-        try {
-          // eslint-disable-next-line @typescript-eslint/no-require-imports
-          translations = require(path);
-          break;
-        } catch {
-          // Try next path
-        }
-      }
-
-      if (translations) {
-        const translationData = translations.default || translations;
-        i18n.addResourceBundle(languageCode, 'translation', translationData, true, true);
-      }
-    } catch (loadError) {
-      // If loading fails, continue with changeLanguage (will fallback to en-US)
-    }
-  }
 }