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

# 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:

{
  "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

import React from 'react';
import { IntlReact } from 'intl-react';
import en from './locales/en.json';
import es from './locales/es.json';

function App() {
  return (
    <IntlReact 
      languages={{ en, es }} 
      defaultLanguage="en"
      detectBrowserLanguage={true}
    >
      <YourApp />
    </IntlReact>
  );
}

export default App;

3. Use Translations

import React from 'react';
import { useTranslation } from 'intl-react';

function Welcome() {
  const { T, setLocale, locale } = useTranslation();

  return (
    <div>
      <h1>{T('greeting', { name: 'Alice' })}</h1>
      <p>{T('items', { count: 5 })}</p>
      <p>{T('weather.hot', { temperature: 30 })}</p>
      <p>{T('profile.title', { name: 'Johnson', gender: 'male' })}</p>
      
      <p>Current language: {locale}</p>
      <button onClick={() => setLocale('es')}>Switch to Spanish</button>
    </div>
  );
}

Advanced Usage

Dynamic Values

Use double underscores to denote dynamic values in your translations:

{
  "welcome": "Welcome to __city__, __name__!"
}

T('welcome', { city: 'Paris', name: 'Alice' })

Pluralization

Use zero, one, and many keys for pluralization:

{
  "apples": {
    "zero": "No apples",
    "one": "One apple",
    "many": "__count__ apples"
  }
}

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:

{
  "greeting": {
    "male": "Welcome, Mr. __name__",
    "female": "Welcome, Ms. __name__"
  }
}

T('greeting', { name: 'Smith', gender: 'male' })
T('greeting', { name: 'Johnson', gender: 'female' })

Locale Management

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:

import { IntlReact } from 'intl-react';
import en from './locales/en.json';
import fr from './locales/fr.json';

export default function App() {
  return (
    <IntlReact languages={{ en, fr }} defaultLanguage="en">
      <NavigationContainer>{/* ... */}</NavigationContainer>
    </IntlReact>
  );
}

Then use it in your components:

import { useTranslation } from 'intl-react';
import { Text, Button } from 'react-native';

function MyScreen() {
  const { T, setLocale } = useTranslation();

  return (
    <>
      <Text>{T('greeting', { name: 'User' })}</Text>
      <Button title="Switch to French" onPress={() => setLocale('fr')} />
    </>
  );
}

TypeScript and Autocompletion

For TypeScript projects, create a custom hook for autocompletion:

// translate.ts
import { useTranslation as useIntlT, Autocomplete, TParams, tr } from 'intl-react';
import en from './locales/en.json';

type Key = Autocomplete<typeof en>;

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:

import { useTranslation } from './translate';

function MyComponent() {
  const { T } = useTranslation();
  return <h1>{T('greeting', { name: 'World' })}</h1>;
}

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 for details.