{"id":36542662,"url":"https://github.com/weprodev/ui-localization","last_synced_at":"2026-01-12T05:49:15.944Z","repository":{"id":323474568,"uuid":"1044038115","full_name":"weprodev/ui-localization","owner":"weprodev","description":"A lightweight, professional localization package for React and React Native applications built on top of i18next and react-i18next. This package provides a clean, type-safe API for managing translations with built-in language switching, variable injection, and component interpolation capabilities.","archived":false,"fork":false,"pushed_at":"2025-12-31T10:36:29.000Z","size":180,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-01-04T15:31:37.430Z","etag":null,"topics":["localization","react","react-native","reactjs","translation","translation-package","ui-localization"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@weprodev/ui-localization","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weprodev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-25T05:12:39.000Z","updated_at":"2025-12-31T10:36:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/weprodev/ui-localization","commit_stats":null,"previous_names":["weprodev/ui-localization"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/weprodev/ui-localization","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weprodev%2Fui-localization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weprodev%2Fui-localization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weprodev%2Fui-localization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weprodev%2Fui-localization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weprodev","download_url":"https://codeload.github.com/weprodev/ui-localization/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weprodev%2Fui-localization/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28335317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["localization","react","react-native","reactjs","translation","translation-package","ui-localization"],"created_at":"2026-01-12T05:49:13.801Z","updated_at":"2026-01-12T05:49:15.935Z","avatar_url":"https://github.com/weprodev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @weprodev/ui-localization\n\nA lightweight, professional localization package for React and React Native applications built on top of i18next and react-i18next. This package provides a clean, type-safe API for managing translations with built-in language switching, variable injection, and component interpolation capabilities.\n\n## ✨ Features\n\n- 🌐 **Simple React Hooks** - Clean, intuitive hooks for translations and language management\n- 🔄 **Language Switching** - Built-in language switching with persistence\n- 📝 **Type-Safe Variable Injection** - Dynamic content insertion with compile-time parameter validation\n- 🧩 **Unified Component Interpolation** - Embed React components within translations using the same `t` function\n- 🔍 **Translation Validation** - CLI tools to ensure translation consistency\n- 🔄 **Translation Sync** - Automated synchronization of translation files\n- 📱 **React Native Support** - Full compatibility with React Native applications\n- 🛡️ **Full Type Safety** - TypeScript support with type-safe keys, parameters, and component interpolation\n- ⚡ **Performance Optimized** - Lightweight wrapper with minimal overhead\n\n## 📦 Installation\n\n```bash\nnpm install @weprodev/ui-localization\n```\n\n## 🚀 Quick Start\n\n### React Applications\n\n#### 1. Create Translation Files\n\nCreate a `translations` directory in your project with language files. **Important:** Use `as const` to enable type-safe parameter validation:\n\n```typescript\n// translations/en.ts\nconst en = {\n  common: {\n    hello: \"Hello {{name}}!\",\n    welcome: \"Welcome {{name}}!\",\n    goodbye: \"Goodbye {{name}}!\",\n    greeting: \"Hello, {{name}}!\"\n  },\n  auth: {\n    login: \"Login\",\n    signup: \"Sign Up\",\n    forgotPassword: \"Forgot Password\",\n    welcomeMessage: \"Welcome \u003cstrong\u003e{{name}}\u003c/strong\u003e! Please \u003clink\u003esign in\u003c/link\u003e to continue.\"\n  },\n  dashboard: {\n    title: \"Dashboard\",\n    summary: \"Summary\",\n    recentActivity: \"Recent Activity\"\n  }\n} as const;\n\nexport default en;\n```\n\n```typescript\n// translations/es.ts\nconst es = {\n  common: {\n    hello: \"Hola {{name}}!\",\n    welcome: \"Bienvenido {{name}}!\",\n    goodbye: \"Adiós {{name}}!\",\n    greeting: \"¡Hola, {{name}}!\"\n  },\n  auth: {\n    login: \"Iniciar sesión\",\n    signup: \"Registrarse\",\n    forgotPassword: \"Contraseña olvidada\",\n    welcomeMessage: \"Bienvenido \u003cstrong\u003e{{name}}\u003c/strong\u003e! Por favor \u003clink\u003einicia sesión\u003c/link\u003e para continuar.\"\n  },\n  dashboard: {\n    title: \"Panel de control\",\n    summary: \"Resumen\",\n    recentActivity: \"Actividad reciente\"\n  }\n} as const;\n\nexport default es;\n```\n\n#### 2. Create Localization Configuration\n\n```typescript\n// src/localizationConfig.ts\nimport { LocalizationConfig, LanguageStore } from '@weprodev/ui-localization';\nimport en from '../translations/en';\nimport es from '../translations/es';\n\n// Optional: Create a custom language store for persistence\nclass CustomLanguageStore implements LanguageStore {\n  getLanguage(): string | null {\n    return localStorage.getItem(\"app-language\") || null;\n  }\n\n  setLanguage(language: string): void {\n    localStorage.setItem(\"app-language\", language);\n  }\n}\n\nexport const localizationConfig: LocalizationConfig = {\n  resources: {\n    en: { translation: en },\n    es: { translation: es }\n  },\n  fallbackLng: 'en',\n  languageStore: new CustomLanguageStore()\n};\n```\n\n#### 3. Initialize Localization\n\n```typescript\n// src/index.tsx\nimport React, { StrictMode } from 'react';\nimport ReactDOM from 'react-dom/client';\nimport { initLocalization } from '@weprodev/ui-localization';\nimport { localizationConfig } from './localizationConfig';\nimport App from './App';\n\nconst rootElement = document.getElementById('root');\n\n// Initialize localization before rendering the app\ninitLocalization(localizationConfig).then(() =\u003e {\n  ReactDOM.createRoot(rootElement).render(\n    \u003cStrictMode\u003e\n      \u003cApp /\u003e\n    \u003c/StrictMode\u003e\n  );\n});\n```\n\n#### 4. Use Translations in Components\n\n```typescript\n// src/components/Welcome.tsx\nimport React from 'react';\nimport { useTranslation } from '@weprodev/ui-localization';\nimport en from '../translations/en';\n\nconst Welcome: React.FC\u003c{ name: string }\u003e = ({ name }) =\u003e {\n  // Type-safe translation hook with path-based keys\n  const { t } = useTranslation\u003ctypeof en\u003e();\n  \n  return (\n    \u003cdiv\u003e\n      {/* TypeScript requires 'name' parameter because translation has {{name}} placeholder */}\n      \u003ch1\u003e{t('common.welcome', { name })}\u003c/h1\u003e\n      \u003cp\u003e{t('common.hello', { name })}\u003c/p\u003e\n      {/* TypeScript will error if you use invalid keys like t('common.invalid') */}\n      {/* TypeScript will error if you forget required parameters */}\n    \u003c/div\u003e\n  );\n};\n\nexport default Welcome;\n```\n\n**Alternative: Create a custom hook for better reusability**\n\n```typescript\n// src/hooks/useAppTranslation.ts\nimport { useTranslation } from '@weprodev/ui-localization';\nimport en from '../translations/en';\n\nexport const useAppTranslation = () =\u003e {\n  return useTranslation\u003ctypeof en\u003e();\n};\n\n// Usage in components\nimport { useAppTranslation } from '../hooks/useAppTranslation';\n\nconst Welcome: React.FC = () =\u003e {\n  const { t } = useAppTranslation();\n  \n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003e{t('common.welcome')}\u003c/h1\u003e {/* Full intellisense and type safety */}\n      \u003cp\u003e{t('common.hello')}\u003c/p\u003e\n      {/* t('common.invalid') will show TypeScript error */}\n    \u003c/div\u003e\n  );\n};\n```\n\n**Important:** For type-safe parameter validation to work, your translation files must use `as const`. This ensures TypeScript preserves literal string types, allowing the system to extract parameter names from placeholders like `{{name}}`.\n\n**Troubleshooting:** If you encounter TypeScript errors with the type-safe hook, you can use `useTranslationFallback()` as an escape hatch. See the API Reference for details.\n\n#### 5. Language Switching\n\n```typescript\n// src/components/LanguageSwitcher.tsx\nimport React from 'react';\nimport { useLanguage } from '@weprodev/ui-localization';\n\nconst LanguageSwitcher: React.FC = () =\u003e {\n  const { currentLanguage, changeLanguage, availableLanguages } = useLanguage();\n  \n  return (\n    \u003cselect \n      value={currentLanguage} \n      onChange={(e) =\u003e changeLanguage(e.target.value)}\n    \u003e\n      {availableLanguages.map(lang =\u003e (\n        \u003coption key={lang} value={lang}\u003e\n          {lang.toUpperCase()}\n        \u003c/option\u003e\n      ))}\n    \u003c/select\u003e\n  );\n};\n\nexport default LanguageSwitcher;\n```\n\n### React Native Applications\n\n#### 1. Create Translation Files\n\nSame structure as React applications (see above).\n\n#### 2. Create Localization Configuration\n\n```typescript\n// src/localizationConfig.ts\nimport { LocalizationConfig, LanguageStore } from '@weprodev/ui-localization';\nimport AsyncStorage from '@react-native-async-storage/async-storage';\nimport en from '../translations/en';\nimport es from '../translations/es';\n\n// React Native language store using AsyncStorage\nclass ReactNativeLanguageStore implements LanguageStore {\n  async getLanguage(): Promise\u003cstring | null\u003e {\n    try {\n      return await AsyncStorage.getItem(\"app-language\");\n    } catch {\n      return null;\n    }\n  }\n\n  async setLanguage(language: string): Promise\u003cvoid\u003e {\n    try {\n      await AsyncStorage.setItem(\"app-language\", language);\n    } catch {\n      // Handle storage error silently\n    }\n  }\n}\n\nexport const localizationConfig: LocalizationConfig = {\n  resources: {\n    en: { translation: en },\n    es: { translation: es }\n  },\n  fallbackLng: 'en',\n  languageStore: new ReactNativeLanguageStore()\n};\n```\n\n#### 3. Initialize Localization\n\n```typescript\n// src/App.tsx\nimport React, { useEffect, useState } from 'react';\nimport { View, Text } from 'react-native';\nimport { initLocalization } from '@weprodev/ui-localization';\nimport { localizationConfig } from './localizationConfig';\n\nconst App: React.FC = () =\u003e {\n  const [isInitialized, setIsInitialized] = useState(false);\n\n  useEffect(() =\u003e {\n    initLocalization(localizationConfig).then(() =\u003e {\n      setIsInitialized(true);\n    });\n  }, []);\n\n  if (!isInitialized) {\n    return (\n      \u003cView style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}\u003e\n        \u003cText\u003eLoading...\u003c/Text\u003e\n      \u003c/View\u003e\n    );\n  }\n\n  return (\n    \u003cView style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}\u003e\n      {/* Your app content */}\n    \u003c/View\u003e\n  );\n};\n\nexport default App;\n```\n\n#### 4. Use Translations in React Native Components\n\n```typescript\n// src/components/Welcome.tsx\nimport React from 'react';\nimport { View, Text, StyleSheet } from 'react-native';\nimport { useTranslation } from '@weprodev/ui-localization';\nimport en from '../translations/en';\n\nconst Welcome: React.FC\u003c{ name: string }\u003e = ({ name }) =\u003e {\n  // Type-safe translation hook with path-based keys\n  const { t } = useTranslation\u003ctypeof en\u003e();\n  \n  return (\n    \u003cView style={styles.container}\u003e\n      \u003cText style={styles.title}\u003e{t('common.welcome', { name })}\u003c/Text\u003e\n      \u003cText style={styles.subtitle}\u003e{t('common.hello', { name })}\u003c/Text\u003e\n    \u003c/View\u003e\n  );\n};\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    padding: 20,\n  },\n  title: {\n    fontSize: 24,\n    fontWeight: 'bold',\n    marginBottom: 10,\n  },\n  subtitle: {\n    fontSize: 16,\n    color: '#666',\n  },\n});\n\nexport default Welcome;\n```\n\n#### 5. Language Switching in React Native\n\n```typescript\n// src/components/LanguageSwitcher.tsx\nimport React from 'react';\nimport { View, Text, TouchableOpacity, StyleSheet } from 'react-native';\nimport { useLanguage } from '@weprodev/ui-localization';\n\nconst LanguageSwitcher: React.FC = () =\u003e {\n  const { currentLanguage, changeLanguage, availableLanguages } = useLanguage();\n  \n  return (\n    \u003cView style={styles.container}\u003e\n      \u003cText style={styles.label}\u003eLanguage:\u003c/Text\u003e\n      \u003cView style={styles.buttonContainer}\u003e\n        {availableLanguages.map(lang =\u003e (\n          \u003cTouchableOpacity\n            key={lang}\n            style={[\n              styles.button,\n              currentLanguage === lang \u0026\u0026 styles.activeButton\n            ]}\n            onPress={() =\u003e changeLanguage(lang)}\n          \u003e\n            \u003cText style={[\n              styles.buttonText,\n              currentLanguage === lang \u0026\u0026 styles.activeButtonText\n            ]}\u003e\n              {lang.toUpperCase()}\n            \u003c/Text\u003e\n          \u003c/TouchableOpacity\u003e\n        ))}\n      \u003c/View\u003e\n    \u003c/View\u003e\n  );\n};\n\nconst styles = StyleSheet.create({\n  container: {\n    padding: 20,\n  },\n  label: {\n    fontSize: 16,\n    fontWeight: 'bold',\n    marginBottom: 10,\n  },\n  buttonContainer: {\n    flexDirection: 'row',\n    gap: 10,\n  },\n  button: {\n    paddingHorizontal: 16,\n    paddingVertical: 8,\n    borderRadius: 4,\n    borderWidth: 1,\n    borderColor: '#ddd',\n  },\n  activeButton: {\n    backgroundColor: '#007AFF',\n    borderColor: '#007AFF',\n  },\n  buttonText: {\n    fontSize: 14,\n    color: '#333',\n  },\n  activeButtonText: {\n    color: '#fff',\n  },\n});\n\nexport default LanguageSwitcher;\n```\n\n## 🔧 Advanced Usage\n\n### Translation with Variables (Type-Safe Parameters)\n\nThe `t` function enforces type-safe parameters based on placeholders in your translation strings. Parameters are **required** when placeholders exist, and **optional** when they don't.\n\n```typescript\nimport { useTranslation } from '@weprodev/ui-localization';\nimport en from '../translations/en';\n\nconst Greeting: React.FC\u003c{ name: string }\u003e = ({ name }) =\u003e {\n  const { t } = useTranslation\u003ctypeof en\u003e();\n  \n  // Translation: \"common.greeting\": \"Hello, {{name}}!\"\n  // ✅ TypeScript requires the 'name' parameter\n  const greeting = t('common.greeting', { name });\n  \n  // ❌ TypeScript error: missing required parameter 'name'\n  // const greeting = t('common.greeting');\n  \n  // ❌ TypeScript error: wrong parameter name\n  // const greeting = t('common.greeting', { wrongName: name });\n  \n  // ✅ No parameters needed for translations without placeholders\n  const title = t('dashboard.title');\n  \n  return \u003cp\u003e{greeting}\u003c/p\u003e;\n};\n```\n\n### Translation with Component Interpolation\n\nThe unified `t` function supports both string and component interpolation. When you pass a `components` object as the third argument, it returns a React element instead of a string.\n\n```typescript\nimport { useTranslation } from '@weprodev/ui-localization';\nimport en from '../translations/en';\n\nconst WelcomeMessage: React.FC\u003c{ name: string }\u003e = ({ name }) =\u003e {\n  const { t } = useTranslation\u003ctypeof en\u003e();\n  \n  // Translation: \"auth.welcomeMessage\": \"Welcome \u003cstrong\u003e{{name}}\u003c/strong\u003e! Please \u003clink\u003esign in\u003c/link\u003e to continue.\"\n  // The translation string must contain matching HTML-like tags (\u003cstrong\u003e, \u003clink\u003e, etc.)\n  const welcomeElement = t(\n    'auth.welcomeMessage',\n    { name },\n    {\n      strong: \u003cstrong className=\"highlight\" /\u003e,\n      link: (props: { children?: React.ReactNode }) =\u003e (\n        \u003ca href=\"#login\" className=\"link-button\"\u003e\n          {props.children}\n        \u003c/a\u003e\n      )\n    }\n  );\n  \n  // Returns JSX.Element when components are provided\n  return \u003cdiv\u003e{welcomeElement}\u003c/div\u003e;\n};\n```\n\n**Important Notes:**\n- Component interpolation only works when the translation string contains matching HTML-like tags (e.g., `\u003cstrong\u003e`, `\u003clink\u003e`)\n- The component keys in your `components` object must match the tag names in the translation\n- For self-closing tags like `\u003cstrong /\u003e`, use self-closing components\n- For tags with content like `\u003clink\u003etext\u003c/link\u003e`, use function components that accept `props.children`\n\n\n### Usage Outside React Components\n\nFor utility functions or other non-component files where hooks are not available, you can use `createTranslation` to get a type-safe `t` function.\n\n```typescript\nimport { createTranslation } from '@weprodev/ui-localization';\nimport en from '../translations/en';\n\n// Create a standalone translation function\nconst t = createTranslation\u003ctypeof en\u003e();\n\n// Basic usage - Returns string\nconst greeting = t('common.hello');\n\n// With parameters - Returns string\nconst message = t('common.welcome', { name: 'World' });\n\n// With components - Returns JSX.Element\n// Useful for creating localized constants with React elements\nconst content = t('common.info', undefined, {\n  link: \u003ca href=\"/more\"\u003eMore\u003c/a\u003e\n});\n```\n\n\n## 🛠️ Translation Management Tools\n\nThe package includes powerful CLI tools to help manage your translations. You can use these tools in multiple ways:\n\n### Option 1: Using NPM Scripts (Recommended)\n\nAdd these commands to your project's `package.json` scripts:\n\n```json\n{\n  \"scripts\": {\n    \"translation:validate\": \"wpd-translation-validate --dir ./translations --source en\",\n    \"translation:sync\": \"wpd-translation-sync --dir ./translations --source en\"\n  }\n}\n```\n\nThen run:\n\n```bash\nnpm run translation:validate\nnpm run translation:sync\n```\n\n**Customizing paths:**\n\nModify the scripts in your `package.json` to use different directories or source language:\n\n```json\n{\n  \"scripts\": {\n    \"translation:validate\": \"wpd-translation-validate --dir ./src/translations --source es\",\n    \"translation:sync\": \"wpd-translation-sync --dir ./src/translations --source es\"\n  }\n}\n```\n\n### Option 2: Using npx (Direct CLI)\n\nRun the CLI tools directly via npx:\n\n```bash\n# Validate translations\nnpx wpd-translation-validate --dir ./translations --source en\n\n# Sync translations\nnpx wpd-translation-sync --dir ./translations --source en\n```\n\n### What These Tools Do\n\n**Validate Translations** (`validate-translations`)\n- Checks if all language files have the same keys as the source language\n- Reports missing keys for each language file\n- Exits with error code if inconsistencies are found\n- Perfect for CI/CD integration\n\n**Sync Translations** (`sync-translations`)\n- Adds missing keys from the source language to all other language files\n- Preserves existing translations\n- Sets empty string values for new keys (ready for translation)\n- Updates translation files automatically\n\n### CI/CD Integration\n\nWe recommend running `translation:validate` as part of your CI pipeline to ensure translation consistency:\n\n```yaml\n# .github/workflows/ci.yml\n- name: Validate Translations\n  run: npm run translation:validate\n```\n\n## 📚 API Reference\n\n### Hooks\n\n#### `useTranslation\u003cT\u003e()`\nReturns a type-safe translation function with intellisense support and type-safe parameter validation.\n\n**Parameters:**\n- None (the translation object type `T` is provided as a generic parameter for type safety)\n\n**Returns:** Object with `t` function that accepts type-safe translation keys\n\n**The `t` function supports two modes:**\n\n1. **String interpolation** (returns `string`):\n```typescript\nimport en from '../translations/en';\n\nconst { t } = useTranslation\u003ctypeof en\u003e();\n\n// No parameters needed for translations without placeholders\nconst title = t('dashboard.title'); // ✅ Returns string\n\n// Parameters required when placeholders exist\nconst greeting = t('common.greeting', { name: 'John' }); // ✅ Returns string\nconst greeting = t('common.greeting'); // ❌ TypeScript error: missing required parameter\n```\n\n2. **Component interpolation** (returns `JSX.Element`):\n```typescript\n// Pass components as third argument\nconst welcomeElement = t(\n  'auth.welcomeMessage',\n  { name: 'Alice' },\n  {\n    strong: \u003cstrong className=\"highlight\" /\u003e,\n    link: (props) =\u003e \u003ca href=\"#login\"\u003e{props.children}\u003c/a\u003e\n  }\n); // ✅ Returns JSX.Element\n```\n\n**Type-Safe Parameters:**\n- Parameters are **required** when the translation string contains placeholders like `{{name}}`\n- Parameters are **optional** when the translation has no placeholders\n- TypeScript validates parameter names match the placeholders in the translation\n\n**Note:** For better reusability, consider creating a custom hook:\n\n```typescript\n// src/hooks/useAppTranslation.ts\nimport { useTranslation } from '@weprodev/ui-localization';\nimport en from '../translations/en';\n\nexport const useAppTranslation = () =\u003e {\n  return useTranslation\u003ctypeof en\u003e();\n};\n\n// Usage\nconst { t } = useAppTranslation();\nconst text = t('common.welcome', { name: 'User' }); // Full type safety and intellisense\n```\n\n#### `useLanguage()`\nProvides language management functionality.\n\n```typescript\nconst { currentLanguage, changeLanguage, availableLanguages } = useLanguage();\n```\n\n#### `useTranslationFallback()`\n**⚠️ Escape hatch hook - use only when the main `useTranslation` hook has TypeScript issues.**\n\nReturns the raw i18next translation function without type safety. This should only be used in rare edge cases where the type-safe hook encounters problems.\n\n```typescript\n// Only use when useTranslation has TypeScript errors\nconst t = useTranslationFallback();\nconst text = t('common.hello'); // No type safety - standard i18next usage\nconst withVars = t('greeting', { name: 'John' });\n```\n\n**Note:** The main `useTranslation` hook should be preferred in 99% of cases.\n\n### Core Functions\n\n#### `initLocalization(config)`\nInitializes the localization system.\n\n```typescript\nawait initLocalization({\n  resources: { en: { translation: enTranslations } },\n  fallbackLng: 'en',\n  languageStore: new CustomLanguageStore()\n});\n```\n\n### Types\n\n#### `LanguageStore`\nInterface for custom language storage implementations.\n\n```typescript\ninterface LanguageStore {\n  getLanguage(): string | null;\n  setLanguage(language: string): void;\n}\n```\n\n#### `LocalizationConfig`\nConfiguration object for localization initialization.\n\n```typescript\ninterface LocalizationConfig {\n  resources: Resource;\n  fallbackLng?: string;\n  compatibilityJSON?: \"v4\";\n  interpolation?: {\n    escapeValue?: boolean;\n  };\n  languageStore?: LanguageStore;\n}\n```\n\n#### `ComponentMap`\nType for component interpolation map. Supports both React elements and function components.\n\n```typescript\ntype ComponentMap = {\n  [key: string]: \n    | React.ReactElement\n    | ((props: { children?: React.ReactNode; [key: string]: any }) =\u003e React.ReactElement)\n}\n```\n\n#### `TranslateFunction\u003cT\u003e`\nType definition for the type-safe translation function.\n\n```typescript\ntype TranslateFunction\u003cT extends NestedRecord\u003e\n```\n\n#### `UseTranslationReturn\u003cT\u003e`\nReturn type of the `useTranslation` hook.\n\n```typescript\ninterface UseTranslationReturn\u003cT extends NestedRecord\u003e {\n  t: TranslateFunction\u003cT\u003e;\n}\n```\n\n#### `NestedRecord`\nBase type for translation resources, allowing recursive nesting of primitive values.\n\n```typescript\ntype NestedRecord = { \n  [key: string]: string | number | boolean | null | undefined | NestedRecord \n};\n```\n\n\n## 🆘 Support\n\nFor support, bug reports, or feature requests, please contact the WeProDev team or create an issue in our internal repository.\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n## 🔗 Links\n\n- [i18next Documentation](https://www.i18next.com/)\n- [react-i18next Documentation](https://react.i18next.com/)\n\n---\n\n**@weprodev/ui-localization** - Professional localization solution by WeProDev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweprodev%2Fui-localization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweprodev%2Fui-localization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweprodev%2Fui-localization/lists"}