@umituz/react-native-localization 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ümit UZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,292 @@
+# @umituz/react-native-localization
+
+Universal localization system for React Native apps with i18n support. Built with Domain-Driven Design principles and TypeScript.
+
+## Features
+
+- **29+ Language Support**: Pre-configured support for 29 languages including RTL languages (Arabic)
+- **Automatic Device Locale Detection**: Automatically detects and applies device language on first launch
+- **Persistent Language Preferences**: Saves user's language choice using AsyncStorage
+- **Type-Safe**: Full TypeScript support with type definitions
+- **Zero Configuration**: Works out of the box with sensible defaults
+- **Production Ready**: Battle-tested in production apps
+- **Lightweight**: Minimal dependencies with tree-shakeable exports
+
+## Installation
+
+```bash
+npm install @umituz/react-native-localization
+# or
+yarn add @umituz/react-native-localization
+```
+
+### Peer Dependencies
+
+Make sure you have the following peer dependencies installed:
+
+```bash
+npm install zustand i18next react-i18next expo-localization @react-native-async-storage/async-storage
+```
+
+## Quick Start
+
+### 1. Wrap Your App with LocalizationProvider
+
+```tsx
+import { LocalizationProvider } from '@umituz/react-native-localization';
+
+export default function App() {
+  return (
+    <LocalizationProvider>
+      <YourApp />
+    </LocalizationProvider>
+  );
+}
+```
+
+### 2. Use Localization in Your Components
+
+```tsx
+import { useLocalization } from '@umituz/react-native-localization';
+
+function MyComponent() {
+  const { t, currentLanguage, setLanguage } = useLocalization();
+
+  return (
+    <View>
+      <Text>{t('general.welcome')}</Text>
+      <Text>Current Language: {currentLanguage}</Text>
+      <Button title="Switch to Turkish" onPress={() => setLanguage('tr-TR')} />
+    </View>
+  );
+}
+```
+
+## API Reference
+
+### `useLocalization()`
+
+Main hook to access localization functionality.
+
+**Returns:**
+- `t`: Translation function
+- `currentLanguage`: Current language code (e.g., 'en-US')
+- `currentLanguageObject`: Full language object with metadata
+- `isRTL`: Boolean indicating if current language is RTL
+- `isInitialized`: Boolean indicating if localization is ready
+- `supportedLanguages`: Array of all supported languages
+- `setLanguage`: Function to change language
+- `initialize`: Function to manually initialize (auto-called by provider)
+
+### `LocalizationProvider`
+
+Component that initializes the localization system. Wrap your app with this component.
+
+```tsx
+<LocalizationProvider>
+  <App />
+</LocalizationProvider>
+```
+
+### Helper Functions
+
+#### `getLanguageByCode(code: string)`
+
+Get language object by language code.
+
+```tsx
+import { getLanguageByCode } from '@umituz/react-native-localization';
+
+const language = getLanguageByCode('en-US');
+// Returns: { code: 'en-US', name: 'English', nativeName: 'English', flag: '🇺🇸', rtl: false }
+```
+
+#### `getDefaultLanguage()`
+
+Get the default language object (English US).
+
+```tsx
+import { getDefaultLanguage } from '@umituz/react-native-localization';
+
+const defaultLang = getDefaultLanguage();
+```
+
+#### `getDeviceLocale()`
+
+Get device's locale and map it to a supported language.
+
+```tsx
+import { getDeviceLocale } from '@umituz/react-native-localization';
+
+const deviceLanguage = getDeviceLocale();
+```
+
+## Supported Languages
+
+The package comes with pre-configured support for 29 languages:
+
+| Language | Code | RTL |
+|----------|------|-----|
+| English | en-US | No |
+| Arabic | ar-SA | Yes |
+| Bulgarian | bg-BG | No |
+| Czech | cs-CZ | No |
+| Danish | da-DK | No |
+| German | de-DE | No |
+| Spanish | es-ES | No |
+| Finnish | fi-FI | No |
+| French | fr-FR | No |
+| Hindi | hi-IN | No |
+| Hungarian | hu-HU | No |
+| Indonesian | id-ID | No |
+| Italian | it-IT | No |
+| Japanese | ja-JP | No |
+| Korean | ko-KR | No |
+| Malay | ms-MY | No |
+| Dutch | nl-NL | No |
+| Norwegian | no-NO | No |
+| Polish | pl-PL | No |
+| Portuguese | pt-PT | No |
+| Romanian | ro-RO | No |
+| Russian | ru-RU | No |
+| Swedish | sv-SE | No |
+| Thai | th-TH | No |
+| Filipino | tl-PH | No |
+| Turkish | tr-TR | No |
+| Ukrainian | uk-UA | No |
+| Vietnamese | vi-VN | No |
+| Chinese (Simplified) | zh-CN | No |
+
+## Translation Structure
+
+The package includes common translations organized by domain:
+
+- `animation`: Animation-related translations
+- `audio`: Audio-related translations
+- `datetime`: Date and time translations
+- `emoji`: Emoji-related translations
+- `errors`: Error messages
+- `forms`: Form labels and validation
+- `general`: General UI text
+- `icons`: Icon labels
+- `location`: Location-related translations
+- `media`: Media-related translations
+- `navigation`: Navigation labels
+- `onboarding`: Onboarding flow text
+- `settings`: Settings screen text
+- `toast`: Toast notification messages
+
+### Example Translation Usage
+
+```tsx
+// Access nested translations
+t('general.welcome')
+t('errors.network.title')
+t('settings.language.title')
+```
+
+## Advanced Usage
+
+### Language Selector Component
+
+```tsx
+import { useLocalization, SUPPORTED_LANGUAGES } from '@umituz/react-native-localization';
+import { FlatList, TouchableOpacity, Text } from 'react-native';
+
+function LanguageSelector() {
+  const { currentLanguage, setLanguage } = useLocalization();
+
+  return (
+    <FlatList
+      data={SUPPORTED_LANGUAGES}
+      keyExtractor={(item) => item.code}
+      renderItem={({ item }) => (
+        <TouchableOpacity onPress={() => setLanguage(item.code)}>
+          <Text>
+            {item.flag} {item.nativeName}
+            {currentLanguage === item.code && ' ✓'}
+          </Text>
+        </TouchableOpacity>
+      )}
+    />
+  );
+}
+```
+
+### RTL Support
+
+```tsx
+import { useLocalization } from '@umituz/react-native-localization';
+import { I18nManager } from 'react-native';
+
+function MyComponent() {
+  const { isRTL } = useLocalization();
+
+  // Apply RTL layout
+  React.useEffect(() => {
+    I18nManager.forceRTL(isRTL);
+  }, [isRTL]);
+
+  return <View style={{ flexDirection: isRTL ? 'row-reverse' : 'row' }} />;
+}
+```
+
+### Custom Translations
+
+You can extend the translations by adding your own:
+
+```tsx
+import { i18n } from '@umituz/react-native-localization';
+
+// Add custom translations
+i18n.addResources('en-US', 'translation', {
+  myFeature: {
+    title: 'My Feature',
+    description: 'Feature description'
+  }
+});
+
+// Use in components
+const { t } = useLocalization();
+console.log(t('myFeature.title')); // 'My Feature'
+```
+
+## TypeScript Support
+
+The package is written in TypeScript and includes full type definitions.
+
+```tsx
+import type { Language } from '@umituz/react-native-localization';
+
+const language: Language = {
+  code: 'en-US',
+  name: 'English',
+  nativeName: 'English',
+  flag: '🇺🇸',
+  rtl: false
+};
+```
+
+## Architecture
+
+Built with Domain-Driven Design (DDD) principles:
+
+- **Domain Layer**: Core business logic and interfaces
+- **Infrastructure Layer**: Implementation details (storage, i18n config, locales)
+- **Presentation Layer**: React components and hooks
+
+## Contributing
+
+Contributions are welcome! Please read the contributing guidelines before submitting PRs.
+
+## License
+
+MIT
+
+## Author
+
+Ümit UZ <umit@umituz.com>
+
+## Repository
+
+https://github.com/umituz/react-native-localization

package/lib/domain/repositories/ILocalizationRepository.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Localization Repository Interface
+ * Defines language configuration and types
+ */
+export interface Language {
+    code: string;
+    name: string;
+    nativeName: string;
+    flag: string;
+    rtl?: boolean;
+}
+export interface ILocalizationRepository {
+    getSupportedLanguages(): Language[];
+    getLanguageByCode(code: string): Language | undefined;
+    isLanguageSupported(code: string): boolean;
+}
+//# sourceMappingURL=ILocalizationRepository.d.ts.map

package/lib/domain/repositories/ILocalizationRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILocalizationRepository.d.ts","sourceRoot":"","sources":["../../../src/domain/repositories/ILocalizationRepository.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,qBAAqB,IAAI,QAAQ,EAAE,CAAC;IACpC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtD,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5C"}

package/lib/domain/repositories/ILocalizationRepository.js

@@ -0,0 +1,6 @@
+/**
+ * Localization Repository Interface
+ * Defines language configuration and types
+ */
+export {};
+//# sourceMappingURL=ILocalizationRepository.js.map

package/lib/domain/repositories/ILocalizationRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILocalizationRepository.js","sourceRoot":"","sources":["../../../src/domain/repositories/ILocalizationRepository.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * React Native Localization
+ * Universal localization system with i18n support for React Native apps
+ */
+export { useLocalization, useLocalizationStore } from './infrastructure/storage/LocalizationStore';
+export { LocalizationProvider } from './infrastructure/components/LocalizationProvider';
+export { default as i18n } from './infrastructure/config/i18n';
+export { SUPPORTED_LANGUAGES, DEFAULT_LANGUAGE, getLanguageByCode, isLanguageSupported, getDefaultLanguage, getDeviceLocale, } from './infrastructure/config/languages';
+export type { Language, ILocalizationRepository } from './domain/repositories/ILocalizationRepository';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAC;AAGnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,kDAAkD,CAAC;AAGxF,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,GAChB,MAAM,mCAAmC,CAAC;AAG3C,YAAY,EAAE,QAAQ,EAAE,uBAAuB,EAAE,MAAM,+CAA+C,CAAC"}

package/lib/index.js

@@ -0,0 +1,12 @@
+/**
+ * React Native Localization
+ * Universal localization system with i18n support for React Native apps
+ */
+// Hooks
+export { useLocalization, useLocalizationStore } from './infrastructure/storage/LocalizationStore';
+// Components
+export { LocalizationProvider } from './infrastructure/components/LocalizationProvider';
+// Configuration
+export { default as i18n } from './infrastructure/config/i18n';
+export { SUPPORTED_LANGUAGES, DEFAULT_LANGUAGE, getLanguageByCode, isLanguageSupported, getDefaultLanguage, getDeviceLocale, } from './infrastructure/config/languages';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAC;AAEnG,aAAa;AACb,OAAO,EAAE,oBAAoB,EAAE,MAAM,kDAAkD,CAAC;AAExF,gBAAgB;AAChB,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,GAChB,MAAM,mCAAmC,CAAC"}

package/lib/infrastructure/components/LocalizationProvider.d.ts

@@ -0,0 +1,11 @@
+/**
+ * LocalizationProvider Component
+ * Initializes localization system on mount
+ */
+import React, { ReactNode } from 'react';
+interface LocalizationProviderProps {
+    children: ReactNode;
+}
+export declare const LocalizationProvider: React.FC<LocalizationProviderProps>;
+export {};
+//# sourceMappingURL=LocalizationProvider.d.ts.map

package/lib/infrastructure/components/LocalizationProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalizationProvider.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/components/LocalizationProvider.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,EAAa,SAAS,EAAE,MAAM,OAAO,CAAC;AAGpD,UAAU,yBAAyB;IACjC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,yBAAyB,CAQpE,CAAC"}

package/lib/infrastructure/components/LocalizationProvider.js

@@ -0,0 +1,14 @@
+/**
+ * LocalizationProvider Component
+ * Initializes localization system on mount
+ */
+import React, { useEffect } from 'react';
+import { useLocalizationStore } from '../storage/LocalizationStore';
+export const LocalizationProvider = ({ children }) => {
+    const initialize = useLocalizationStore((state) => state.initialize);
+    useEffect(() => {
+        initialize();
+    }, [initialize]);
+    return <>{children}</>;
+};
+//# sourceMappingURL=LocalizationProvider.js.map

package/lib/infrastructure/components/LocalizationProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalizationProvider.js","sourceRoot":"","sources":["../../../src/infrastructure/components/LocalizationProvider.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,EAAE,SAAS,EAAa,MAAM,OAAO,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAMpE,MAAM,CAAC,MAAM,oBAAoB,GAAwC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE;IACxF,MAAM,UAAU,GAAG,oBAAoB,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAErE,SAAS,CAAC,GAAG,EAAE;QACb,UAAU,EAAE,CAAC;IACf,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;IAEjB,OAAO,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC;AACzB,CAAC,CAAC"}

package/lib/infrastructure/config/i18n.d.ts

@@ -0,0 +1,7 @@
+/**
+ * i18next Configuration
+ * Nested translation structure - common translations spread, domain translations nested
+ */
+import i18n from 'i18next';
+export default i18n;
+//# sourceMappingURL=i18n.d.ts.map

package/lib/infrastructure/config/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/config/i18n.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,IAAI,MAAM,SAAS,CAAC;AAmD3B,eAAe,IAAI,CAAC"}

package/lib/infrastructure/config/i18n.js

@@ -0,0 +1,49 @@
+/**
+ * i18next Configuration
+ * Nested translation structure - common translations spread, domain translations nested
+ */
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import { DEFAULT_LANGUAGE } from './languages';
+/**
+ * Import all translations from modular folder structure
+ * Each locale has an index.ts that merges all JSON files
+ *
+ * Structure (OFFLINE-ONLY):
+ * locales/
+ *   en-US/  (universal translations in localization domain)
+ *     index.ts (merges common.json, navigation.json, settings.json, onboarding.json, errors.json)
+ *
+ * All translations are offline-compatible and work without backend.
+ */
+// Import universal translations from localization domain
+import localizationEnUS from '../locales/en-US';
+/**
+ * Translation Resources
+ * Nested structure - domain-based organization with direct key access
+ * Example: settings.theme.title, onboarding.welcome.title
+ */
+const resources = {
+    'en-US': {
+        translation: {
+            ...localizationEnUS,
+        },
+    },
+};
+/**
+ * Initialize i18next
+ */
+i18n.use(initReactI18next).init({
+    resources,
+    lng: DEFAULT_LANGUAGE,
+    fallbackLng: DEFAULT_LANGUAGE,
+    interpolation: {
+        escapeValue: false, // React already escapes values
+    },
+    react: {
+        useSuspense: false, // Disable suspense for React Native
+    },
+    compatibilityJSON: 'v4', // Use i18next v4 JSON format
+});
+export default i18n;
+//# sourceMappingURL=i18n.js.map

package/lib/infrastructure/config/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../../../src/infrastructure/config/i18n.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAuB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;;;;;;;GAUG;AAEH,yDAAyD;AACzD,OAAO,gBAAgB,MAAM,kBAAkB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,SAAS,GAAG;IAChB,OAAO,EAAE;QACP,WAAW,EAAE;YACX,GAAG,gBAAgB;SACpB;KACF;CACF,CAAC;AAEF;;GAEG;AACH,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC;IAC9B,SAAS;IACT,GAAG,EAAE,gBAAgB;IACrB,WAAW,EAAE,gBAAgB;IAE7B,aAAa,EAAE;QACb,WAAW,EAAE,KAAK,EAAE,+BAA+B;KACpD;IAED,KAAK,EAAE;QACL,WAAW,EAAE,KAAK,EAAE,oCAAoC;KACzD;IAED,iBAAiB,EAAE,IAAI,EAAE,6BAA6B;CACvD,CAAC,CAAC;AAEH,eAAe,IAAI,CAAC"}

package/lib/infrastructure/config/languages.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Supported Languages Configuration
+ * Complete list of 29 languages supported by the app
+ *
+ * SINGLE SOURCE OF TRUTH: Imports from constants/languages.ts
+ * - All language definitions come from one central location
+ * - Ensures consistency across app.json, i18n config, and UI
+ * - Automatic synchronization between all language configurations
+ *
+ * DEVICE LOCALE DETECTION:
+ * - First launch: Automatically detects device locale
+ * - Fallback: English (en-US) if device locale not supported
+ * - User choice: Persists after manual language selection
+ */
+import { Language } from '../../domain/repositories/ILocalizationRepository';
+export declare const SUPPORTED_LANGUAGES: Language[];
+export declare const DEFAULT_LANGUAGE = "en-US";
+export declare const getLanguageByCode: (code: string) => Language | undefined;
+export declare const isLanguageSupported: (code: string) => boolean;
+export declare const getDefaultLanguage: () => Language;
+/**
+ * Get device locale and map it to supported language
+ * Called ONLY on first launch (when no saved language preference exists)
+ *
+ * @returns Supported language code or DEFAULT_LANGUAGE
+ *
+ * Examples:
+ * - Device: "en" → Returns: "en-US"
+ * - Device: "en-GB" → Returns: "en-US"
+ * - Device: "tr" → Returns: "tr-TR" (if supported)
+ * - Device: "de" → Returns: "en-US" (not supported, fallback)
+ */
+export declare const getDeviceLocale: () => string;
+//# sourceMappingURL=languages.d.ts.map

package/lib/infrastructure/config/languages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"languages.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/config/languages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,mDAAmD,CAAC;AAG7E,eAAO,MAAM,mBAAmB,EAAE,QAAQ,EAAc,CAAC;AAEzD,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAoKxC,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,QAAQ,GAAG,SAE3D,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,OAElD,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAAO,QAErC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,QAAO,MAkClC,CAAC"}