README.md

@plaidev/react-i18n

The most simplest type-safe internationalization library for react.

Getting started

@plaidev/react-i18n can be installed using npm or yarn:

# npm
npm install -S @plaidev/react-i18n

# yarn
yarn add @plaidev/react-i18n

Example

Firstly, react-i18n can be used to declare I18nProvider at the root of your react app.

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App';
import { I18nProvider, browser, ignorePlaceCode } from '@plaidev/react-i18n';

const main = () => {
  const container = document.getElementById('root');
  const root = createRoot(container!);
  root.render(
    <StrictMode>
      <I18nProvider
        fallbackLocale="en"
        detectors={[browser, ignorePlaceCode]}
      >
        <App />
      </I18nProvider>
    </StrictMode>
  );
}

main();

Then, you can use resource of a locale by using useTranslation.

import { useTranslation } from '@plaidev/react-i18n';

export const App = () => {
  const t = useTranslation({
    pt: {
      message: 'bom dia!',
    },
    en: {
      message: 'hello!',
    },
  });
  return <div>
    {t.message}
  </div>
}

Translations

Basic

import { useTranslation } from '@plaidev/react-i18n';

export const Hello = () => {
  const translated = useTranslation({
    ja: {
      hello: 'こんにちは',
      world: '世界',
    },
    en: {
      hello: 'hello',
      world: 'world',
    }
  });
  return <div>
    {translated.hello} {translated.world}
  </div>
}

Inline Translation

import { useInlineTranslation } from '@plaidev/react-i18n';

export const Hello = () => {
  const translated = useInlineTranslation();
  return <div>
    {translated({ en: 'Hello', ja: 'こんにちは' })} {/* "Hello" or "こんにちは" */}
  </div>
}

Interpolation

import { useTranslation } from '@plaidev/react-i18n';

const Hello = () => {
  const { message } = useTranslation({
    ja: {
      message({ name }: { name: string }) {
        return `こんにちは、${name}！`
      }
    },
    en: {
      message({ name }: { name: string }) {
        return `Hello, ${name}!`
      }
    }
  });

  return <div>{message({ name: 'John' })}</div>
}

Singluar / Plurals

import { useTranslation } from '@plaidev/react-i18n';

const Hello = () => {
  const t = useTranslation({
    en: ({ count }: { count: number }) => {
      switch (true) {
        case (x === 0):
          return 'zero'
        case (x === 1):
          return 'one'
        case (x <= 10):
          return "few"
        default:
          return "many"
      }
    }
  })
  return <div>
    {t(5)}
  </div>
}

Formatting

@plaidev/react-i18n supports formatter hooks that wrap Intl.

import {
  useCurrencyFormat,
  useNumberFormat,
  useDateTimeFormat,
  useRelativeTimeFormat,
  useListFormat,
  usePluralRules,
  useTranslation,
} from '@plaidev/react-i18n';

const Hello = () => {
  const currency = useCurrencyFormat();
  const howMuchMessage = useTranslation({
    en: (howMuch: number) => {
      return `This is ${currency(howMuch, 'USD')}`;
    }
  });
  return <div>
    {howMuchMessage(100)}
  </div>
}

Detectors

Cookie Detector

cookie detector detects locale from document.cookie

import {
  I18nProvider,
  cookie,
} from '@plaidev/react-i18n';

<I18nProvider
  fallbackLocale="en"
  detectors={[cookie('something_key')]}
>
  <App />
</I18nProvider>

Browser Detector

browser detector detects locale from window.navigator.

import {
  I18nProvider,
  browser,
} from '@plaidev/react-i18n';

<I18nProvider
  fallbackLocale="en"
  detectors={[browser]}
>
  <App />
</I18nProvider>

Ignore Place Code

ignorePlaceCode ignores a place code from a detected locale.

e.g) ja-JP -> ja

import {
  I18nProvider,
  browser,
  ignorePlaceCode,
} from '@plaidev/react-i18n';

<I18nProvider
  fallbackLocale="en"
  detectors={[browser, ignorePlaceCode]}
>
  <App />
</I18nProvider>

Force to select a specific locale

forcedLocale detect a specific locale that specified by an argument.

import {
  I18nProvider,
  forcedLocale,
} from '@plaidev/react-i18n';

<I18nProvider
  fallbackLocale="en"
  detectors={[forcedLocale('ja')]}
>
  <App />
</I18nProvider>

Other hooks

@plaidev/react-i18n supports the locale setter and the locale getter hooks.

import {
  useLocaleSetting,
  useLocaleSettingValue,
  useSetLocaleSetting,
} from '@plaidev/react-i18n';

export const Example1 = () => {
  const [{ locale }, { setLocale }] = useLocaleSetting();
  return <button onClick={() => setLocale('en')}>{locale}</button>
}

export const Example2 = () => {
  const { locale } = useLocaleSettingValue();
  return <button>{locale}</button>
}

export const Example3 = () => {
  const { setLocale } = useSetLocaleSetting();
  return <button onClick={() => setLocale('en')}>en</button>
}