react-native-i18n-auto

A powerful internationalization (i18n) tool for React Native with full TypeScript support and automatic translation capabilities.

✨ Features

• 🚀 Full TypeScript Support - Complete type safety with proper type definitions and interfaces
• 📦 Automatic Key Extraction - Seamless extraction through custom Babel plugin
• 🌐 Multiple Language Support - Support for 16 major languages out of the box
• 📱 React Native Optimized - Built specifically for React Native applications
• ⚡️ High Performance - Efficient caching system and memory optimization
• 🔄 Event System - Language change event listeners for real-time updates
• 🛠 Easy Configuration - Simple setup and intuitive API
• 🎯 Proxy Support - Convenient dot notation access for translations
• 💾 Smart Caching - Automatic cache management with configurable duration

📥 Installation

# Using npm
npm install --save-dev react-native-i18n-auto
npm install @react-native-async-storage/async-storage

# Using yarn
yarn add -D react-native-i18n-auto
yarn add @react-native-async-storage/async-storage

🛠 Setup

1. Configure TypeScript

Add the following to your tsconfig.json:

{
    "compilerOptions": {
        "resolveJsonModule": true
    }
}

Create an i18n-auto.config.json file in your project root:

{
    "defaultLanguage": "en",
    "supportedLanguages": ["en", "ko", "ja"],
    "localeDir": "locales",
    "sourceDir": ["app", "src"],
    "ignore": [
        "node_modules/**",
        "dist/**",
        "build/**",
        ".git/**",
        "tests/**",
        "**/*.test.*",
        "**/*.spec.*"
    ]
}

🚀 Quick Start Guide

1. Initialize Translation System

Run the following command in your project root:

npx react-native-i18n-auto run

2. Automatic Code Generation

The system will automatically transform your code and generate necessary translation files.

Before:

import { Text } from 'react-native';

export default function App() {
  return <Text>Hello</Text>;
}

After:

import { i18n } from 'react-native-i18n-auto'; //auto generate i18n instance
import { Text } from 'react-native';

export default function App() {
  return <Text>{i18n.t('HELLO')}</Text>;
}

Generated Translation File

A translation file (en.json) will be automatically created:

{
    "HELLO": "Hello"
}

💡 Tip: You can use AI tools like ChatGPT to help translate these keys into different languages.

3. Configure Languages

Set up your languages in your app's entry point (_layout.tsx or App.tsx):

import { i18n } from 'react-native-i18n-auto';
import en from './locales/en.json';
import ko from './locales/ko.json';
import ja from './locales/ja.json';
// Import other language files as needed

i18n.setLocales({
    en,
    ko,
    ja,
    // Add other languages as needed
});

4. Using Translations

There are multiple ways to use translations in your code:

// 1. Function call
i18n.t('HELLO'); // Returns: "Hello"

// 2. Proxy notation (recommended)
i18n.t.HELLO; // Returns: "Hello"

// 3. Nested keys
i18n.t('GREETINGS.HELLO'); // Returns: "Hello" from nested structure

5. Language Management

Setting Up Language State

To properly manage language changes across your app, you should set up a global state management solution:

import React, { createContext, useContext, useState, useEffect } from 'react';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { i18n, LanguageCode } from 'react-native-i18n-auto';

type LanguageContextType = {
    currentLanguage: LanguageCode;
    changeLanguage: (lang: LanguageCode) => void;
};

const LanguageContext = createContext<LanguageContextType | undefined>(undefined);

const STORAGE_KEY = 'USER_LANGUAGE';

export const LanguageProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
    const [currentLanguage, setCurrentLanguage] = useState<LanguageCode>(i18n.getLanguage());

    useEffect(() => {
        AsyncStorage.getItem(STORAGE_KEY).then((savedLang) => {
            if (savedLang && i18n.setLanguage(savedLang as LanguageCode)) {
                setCurrentLanguage(savedLang as LanguageCode);
            }
        });
    }, []);

    const changeLanguage = (lang: LanguageCode) => {
        if (i18n.setLanguage(lang)) {
            setCurrentLanguage(lang);
            AsyncStorage.setItem(STORAGE_KEY, lang);
        }
    };

    return <LanguageContext.Provider value={{ currentLanguage, changeLanguage }}>{children}</LanguageContext.Provider>;
};

export const useLanguage = () => {
    const context = useContext(LanguageContext);
    if (!context) {
        throw new Error('useLanguage must be used within a LanguageProvider');
    }
    return context;
};

Wrap your app with the LanguageProvider:

// App.tsx or equivalent
import { LanguageProvider } from './languageContext';

export default function App() {
    return (
        <LanguageProvider>
            <YourAppContent />
        </LanguageProvider>
    );
}

Using the Language Hook

Now you can change languages anywhere in your app using the useLanguage hook:

import { useLanguage } from './languageContext';

function LanguageSelector() {
    const { currentLanguage, changeLanguage } = useLanguage();

    return (
        <View>
            <Button
                title="English"
                onPress={() => changeLanguage('en')}
                disabled={currentLanguage === 'en'}
            />
            <Button
                title="한국어"
                onPress={() => changeLanguage('ko')}
                disabled={currentLanguage === 'ko'}
            />
            <Button
                title="日本語"
                onPress={() => changeLanguage('ja')}
                disabled={currentLanguage === 'ja'}
            />
        </View>
    );
}

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Additional Features

Event System

You can subscribe to language changes:

// Subscribe to language changes
const unsubscribe = i18n.onLanguageChange(() => {
    console.log('Current language:', i18n.getLanguage());
});

// Cleanup when component unmounts
useEffect(() => {
    return () => unsubscribe();
}, []);

Performance Optimization

The library includes built-in performance optimization features:

// Clear translation cache
i18n.clearCache();

// Optimize memory usage
i18n.optimize();

Language Utilities

Additional utility functions for language management:

// Get all supported languages
const supported = i18n.getSupportedLanguages();

// Get languages that have translations loaded
const available = i18n.getAvailableLanguages();

Type Safety Features

The library provides strong TypeScript support with proper type definitions:

import { i18n, LanguageCode, I18nType } from 'react-native-i18n-auto';

// Type-safe language codes
const setKorean = () => i18n.setLanguage('ko' as LanguageCode);

// Type-safe translation keys (when using with TypeScript)
type TranslationKeys = keyof typeof import('./locales/en.json');
const translate = (key: TranslationKeys) => i18n.t(key);

💡 Tip: You can also integrate this with your backend to sync user language preferences across devices.