react-native-localize-helper

🌍 React Native Localize Helper

A simple, lightweight, and easy-to-use helper library for handling localization (i18n) in your React Native applications.

Designed with simplicity for developers of all levels.

✨ Features

• ✅ Effortless Setup: Initialize translations with minimal configuration.
• ✅ Intuitive Translation: Use the simple t() function for key-based translation.
• ✅ React Hook Integration: Seamlessly use useTranslation() in functional components.
• ✅ Dynamic Placeholders: Easily replace values within translations (e.g., Welcome, {{name}}!).
• ✅ On-the-Fly Language Switching: Change the active language dynamically.
• ✅ Reliable Fallback: Automatically uses a default language for missing keys.
• ✅ Pure JavaScript: Works seamlessly with React Native CLI and Expo CLI without native code.

🚀 Installation

Choose your preferred package manager:

# Using npm
npm install react-native-localize-helper

# Using Yarn
yarn add react-native-localize-helper
🎬 Demo VideoWatch this short video to see react-native-localize-helper in action!Watch the Demo Video on Vimeo📖 Usage GuideFollow these steps to integrate react-native-localize-helper into your app:Step 1: Prepare Your Translation ResourcesYou need an object containing your translations. Keys are language codes (e.g., 'en'), and values are objects mapping translation keys to strings.Option A: Single Object (Simple Apps)Define directly in a JavaScript file (e.g., src/translations.js):// src/translations.js
export const resources = {
  en: { greeting: 'Hello!', welcome: 'Welcome, {{name}}!' },
  es: { greeting: '¡Hola!', welcome: '¡Bienvenido, {{name}}!' },
  // ... other languages
};
Option B: Separate JSON Files (Recommended for Larger Apps)Create individual JSON files for each language in your app project:src/translations/en.json:{ "greeting": "Hello from JSON!", "welcome": "Welcome, {{name}}!" }
src/translations/es.json:{ "greeting": "¡Hola desde JSON!", "welcome": "¡Bienvenido, {{name}}!" }
Then, import and combine them in your app (e.g., in App.js):// App.js (or a dedicated i18n setup file)
import enTranslations from './src/translations/en.json';
import esTranslations from './src/translations/es.json';

const resources = {
  en: enTranslations,
  es: esTranslations,
  // ... import other languages
};
Step 2: Initialize the LibraryCall initLocalization once when your application starts, before rendering any components that need translations. Your main App.js is usually the best place.// App.js
import React from 'react';
import { initLocalization } from 'react-native-localize-helper';
// Import resources (either the direct object or the combined JSON imports)
import { resources } from './src/translations'; // Adjust path if needed
import AppContent from './AppContent'; // Your main app component/navigator

// --- Initialize Localization ---
initLocalization({
  resources: resources,       // Pass the translation data
  defaultLanguage: 'en',      // Fallback language
  initialLanguage: 'en',      // Set the starting language (consider detecting device locale)
});
// --- End Initialization ---

function App() {
  return <AppContent />;
}

export default App;
Step 3: Use Translations in ComponentsImport and use the useTranslation hook within your functional components to access translation capabilities.// src/components/MyComponent.js
import React from 'react';
import { View, Text, Button } from 'react-native';
import { useTranslation } from 'react-native-localize-helper';

const MyComponent = () => {
  // Get the t function, current language, and setter from the hook
  const { t, currentLanguage, setLanguage } = useTranslation();

  return (
    <View>
      <Text>{t('greeting')}</Text>
      <Text>{t('welcome', { name: 'Developer' })}</Text>
      <Text>Current: {currentLanguage.toUpperCase()}</Text>
      <Button title="Switch to Spanish" onPress={() => setLanguage('es')} />
      <Button title="Switch to English" onPress={() => setLanguage('en')} />
    </View>
  );
};

export default MyComponent;
Step 4: Use t() Outside Components (Optional)If you need translations in utility functions or other non-component parts of your code (after initialization), you can import t directly. Ensure initLocalization has already been called.// src/utils/messages.js
import { t } from 'react-native-localize-helper';

export function getWelcomeMessage(name) {
  // Make sure initLocalization was called before this function runs
  return t('welcome', { name: name });
}
⚙️ Integration with State ManagementWhile the library manages its own internal state, you can integrate it with global state managers like Redux or Context API for more complex scenarios, such as persisting language preferences.General Concept:Store the currently selected language code (e.g., 'en') in your global store (Redux, Context, Zustand, etc.).Initialize the library using the language code from your store (initialLanguage).When the language changes in your store (e.g., user selects a new language via a settings screen), use a useEffect hook (or similar mechanism) in a top-level component to call the library's setLanguage() function, keeping it synchronized.When the user interacts with UI elements to change the language (e.g., buttons), dispatch an action to update the language code in your global store, rather than calling the library's setLanguage() directly from the UI component. The synchronization effect (Step 3) will handle updating the library.Example with Redux:Redux Setup:Create a settings slice (or similar) in your Redux store to hold currentLanguage.Define actions like setAppLanguage.Initialization (App.js):import { useSelector } from 'react-redux';
// ... other imports

function AppInitializer() {
  const languageFromStore = useSelector(state => state.settings.currentLanguage) || 'en'; // Get from store

  React.useEffect(() => {
    initLocalization({
      resources: resources,
      defaultLanguage: 'en',
      initialLanguage: languageFromStore, // Use language from store
    });
  }, [languageFromStore]); // Re-init if store language changes drastically (optional)

  return null; // Or render children
}

function App() {
  return (
    <Provider store={store}>
      <AppInitializer />
      <AppContent />
    </Provider>
  );
}
Synchronization (AppInitializer or similar):import { setLanguage as setLibraryLanguage } from 'react-native-localize-helper';
// ... inside AppInitializer component

const languageFromStore = useSelector(state => state.settings.currentLanguage) || 'en';
const libraryLanguageRef = React.useRef(null); // Track library's language

React.useEffect(() => {
  // Only update library if the store language is different
  if (languageFromStore !== libraryLanguageRef.current) {
    setLibraryLanguage(languageFromStore);
    libraryLanguageRef.current = languageFromStore; // Update ref
  }
}, [languageFromStore]); // Run when store language changes
Changing Language (e.g., SettingsScreen.js):import { useDispatch } from 'react-redux';
import { setAppLanguage } from './settingsSlice'; // Your Redux action

const SettingsScreen = () => {
  const dispatch = useDispatch();

  const handlePress = (lang) => {
    dispatch(setAppLanguage(lang)); // Dispatch Redux action
  };

  return (
    <View>
      <Button title="Set English" onPress={() => handlePress('en')} />
      <Button title="Set Spanish" onPress={() => handlePress('es')} />
    </View>
  );
};
Other State Managers (Context API, Zustand, etc.):The principle remains the same: store the language code in the global state, initialize the library with it, and use an effect to synchronize changes from the global store to the library using setLanguage(). Dispatch actions or update the store state to trigger changes.📚 API ReferenceinitLocalization(options)Initializes the library. Call once at app startup.options (object):resources (object): (Required) The translation object (e.g., { en: {...}, es: {...} }).defaultLanguage (string): (Optional, defaults to 'en') Fallback language code.initialLanguage (string): (Optional, defaults to defaultLanguage) Starting language code.t(key, [options])The core translation function.key (string): (Required) The key identifying the string to translate.options (object): (Optional) An object for placeholder replacement (e.g., { name: 'User' } replaces {{name}}).Returns: (string) The translated string, the fallback string, or the key itself.useTranslation()React Hook for use in functional components.Returns: (object) An object containing:t: The translation function t(key, options).currentLanguage: (string) The currently active language code.setLanguage: (language: string) => void A function to change the active language (triggers re-renders in components using the hook).setLanguage(language)Globally sets the active language.language (string): (Required) The language code to switch to (must exist in the initialized resources).getCurrentLanguage()Synchronously returns the currently active language code.Returns: (string) The current language code.🤝 ContributingContributions, issues, and feature requests are welcome! Please check the issues page .Fork the ProjectCreate your Feature Branch (git checkout -b feature/AmazingFeature)Commit your Changes (git commit -m 'Add some AmazingFeature')Push to the Branch (git push origin feature/AmazingFeature)Open a Pull Request📜 LicenseDistributed under the MIT License. See LICENSE file for more information.Happy Coding! 😊