react-native-i18n-auto
Version:
Auto i18n tool for React Native with full TypeScript support
311 lines (229 loc) • 8.04 kB
Markdown
# react-native-i18n-auto
A powerful internationalization (i18n) tool for React Native with full TypeScript support and automatic translation capabilities.
[](https://badge.fury.io/js/react-native-i18n-auto)
[](https://github.com/ellerbrock/typescript-badges/)
[](https://opensource.org/licenses/MIT)
## ✨ 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
```bash
# 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`:
```json
{
"compilerOptions": {
"resolveJsonModule": true
}
}
```
Create an `i18n-auto.config.json` file in your project root:
```json
{
"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:
```bash
npx react-native-i18n-auto run
```
### 2. Automatic Code Generation
The system will automatically transform your code and generate necessary translation files.
#### Before:
```typescript
import { Text } from 'react-native';
export default function App() {
return <Text>Hello</Text>;
}
```
#### After:
```typescript
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:
```json
{
"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`):
```typescript
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:
```typescript
// 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:
```typescript
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`:
```typescript
// 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:
```typescript
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:
```typescript
// 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:
```typescript
// Clear translation cache
i18n.clearCache();
// Optimize memory usage
i18n.optimize();
```
### Language Utilities
Additional utility functions for language management:
```typescript
// 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:
```typescript
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.