https://github.com/rohit1901/intl-react
Internationalize React apps. This library provides React components and an API to format numbers, strings, including pluralization and handling translations. #showcase
https://github.com/rohit1901/intl-react
internationalization javascript library locale react reactnative typescript vite
Last synced: 2 months ago
JSON representation
Internationalize React apps. This library provides React components and an API to format numbers, strings, including pluralization and handling translations. #showcase
- Host: GitHub
- URL: https://github.com/rohit1901/intl-react
- Owner: rohit1901
- License: mit
- Created: 2024-07-23T22:36:42.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-07-02T10:38:36.000Z (about 1 year ago)
- Last Synced: 2025-07-02T11:41:07.947Z (about 1 year ago)
- Topics: internationalization, javascript, library, locale, react, reactnative, typescript, vite
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/intl-react
- Size: 148 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# intl-react
**intl-react** is a lightweight, powerful i18n provider for React applications. It offers full TypeScript support, autocompletion, zero dependencies, and an intuitive API. Perfect for both web and React Native projects.
## Features
- 🌐 Automatic browser language detection
- 📅 Dates support
- 🔢 Smart plural rules for any language
- 🔄 Dynamic translations with multiple keys
- 🗂️ Deep nested key access in JSON translation files
- ⚧️ Gender-aware syntax adaptation
- 📱 React Native compatibility
- 💡 TypeScript autocompletion for translation keys
- 🚀 Performant and lightweight
## Installation
```bash
# Using npm
npm install intl-react
# Using yarn
yarn add intl-react
# Using pnpm
pnpm add intl-react
```
## Quick Start
1. Create your JSON translation files
2. Set up the IntlReact provider
3. Use translations in your components
### 1. Create Translation Files
Example `en.json`:
```json
{
"greeting": "Hello, __name__!",
"items": {
"zero": "No items",
"one": "One item",
"many": "__count__ items"
},
"weather": {
"hot": "It's __temperature__°C outside. Stay hydrated!",
"cold": "It's __temperature__°C outside. Bundle up!"
},
"profile": {
"title": {
"male": "Mr. __name__",
"female": "Ms. __name__"
}
}
}
```
### 2. Set Up Provider
```jsx
import React from 'react';
import { IntlReact } from 'intl-react';
import en from './locales/en.json';
import es from './locales/es.json';
function App() {
return (
);
}
export default App;
```
### 3. Use Translations
```jsx
import React from 'react';
import { useTranslation } from 'intl-react';
function Welcome() {
const { T, setLocale, locale } = useTranslation();
return (
{T('greeting', { name: 'Alice' })}
{T('items', { count: 5 })}
{T('weather.hot', { temperature: 30 })}
{T('profile.title', { name: 'Johnson', gender: 'male' })}
Current language: {locale}
setLocale('es')}>Switch to Spanish
);
}
```
## Advanced Usage
### Dynamic Values
Use double underscores to denote dynamic values in your translations:
```json
{
"welcome": "Welcome to __city__, __name__!"
}
```
```jsx
T('welcome', { city: 'Paris', name: 'Alice' })
```
### Pluralization
Use `zero`, `one`, and `many` keys for pluralization:
```json
{
"apples": {
"zero": "No apples",
"one": "One apple",
"many": "__count__ apples"
}
}
```
```jsx
T('apples', { count: 0 }) // "No apples"
T('apples', { count: 1 }) // "One apple"
T('apples', { count: 5 }) // "5 apples"
```
### Gender-Aware Translations
Use `male` and `female` keys for gender-specific translations:
```json
{
"greeting": {
"male": "Welcome, Mr. __name__",
"female": "Welcome, Ms. __name__"
}
}
```
```jsx
T('greeting', { name: 'Smith', gender: 'male' })
T('greeting', { name: 'Johnson', gender: 'female' })
```
### Locale Management
```jsx
const { setLocale, locale } = useTranslation();
// Get current locale
console.log(locale);
// Change locale
setLocale('fr');
```
## React Native Support
intl-react works seamlessly with React Native. Just wrap your app with the provider:
```jsx
import { IntlReact } from 'intl-react';
import en from './locales/en.json';
import fr from './locales/fr.json';
export default function App() {
return (
{/* ... */}
);
}
```
Then use it in your components:
```jsx
import { useTranslation } from 'intl-react';
import { Text, Button } from 'react-native';
function MyScreen() {
const { T, setLocale } = useTranslation();
return (
<>
{T('greeting', { name: 'User' })}
setLocale('fr')} />
>
);
}
```
## TypeScript and Autocompletion
For TypeScript projects, create a custom hook for autocompletion:
```typescript
// translate.ts
import { useTranslation as useIntlT, Autocomplete, TParams, tr } from 'intl-react';
import en from './locales/en.json';
type Key = Autocomplete;
export const useTranslation = () => {
const { locale, languages, defaultLanguage } = useIntlT();
return {
T: (key: Key, params?: TParams) =>
tr({ locale, languages, defaultLanguage }, key, params),
setLocale: useIntlT().setLocale,
locale: useIntlT().locale,
};
};
```
Now use your custom hook for autocompletion:
```tsx
import { useTranslation } from './translate';
function MyComponent() {
const { T } = useTranslation();
return
{T('greeting', { name: 'World' })}
;
}
```
## API Reference
### IntlReact Props
| Prop | Type | Description |
|------|------|-------------|
| `languages` | `object` | Object containing all translation JSON files |
| `defaultLanguage` | `string` | Default language code |
| `detectBrowserLanguage` | `boolean` | Automatically detect and use browser language |
### useTranslation Hook
| Method/Property | Type | Description |
|-----------------|------|-------------|
| `T` | `function` | Translation function |
| `setLocale` | `function` | Change current locale |
| `locale` | `string` | Current locale code |
## Best Practices
1. Keep translation keys hierarchical and meaningful
2. Use pluralization for countable items
3. Implement gender-aware translations where applicable
4. Leverage TypeScript for type-safe translations
5. Regularly update and sync translation files across languages
## License
intl-react is MIT licensed. See [LICENSE](LICENSE.md) for details.