React-T #

Simple translation module for React applications.

tl;dr #

• Install by executing npm install @wojtekmaj/react-t or yarn add @wojtekmaj/react-t.
• Setup by adding import { TProvider } from '@wojtekmaj/react-t' and wrapping your app in <TProvider />.
• Add languages by creating a JSON file, like this:

  {
    "Hello world!": "Hallo Welt!"
  }
  

  and adding languageFiles to <TProvider />, like this:

  <TProvider languageFiles={{ 'de-DE': () => import('./de-DE.json') }} />
  

• Use by adding import T from '@wojtekmaj/react-t' and wrapping your text in <T />.

Getting started #

Compatibility #

Your project needs to use React 16.8 or later.

React-T is also compatible with React Native.

Installation #

Add React-T to your project by executing npm install @wojtekmaj/react-t or yarn add @wojtekmaj/react-t.

Setting up #

Here's an example of basic setup:

import { createRoot } from 'react-dom/client';
import { TProvider } from '@wojtekmaj/react-t';

import Root from './Root';

const languageFiles = {
  'de-DE': () => import('./de-DE.json'),
};

createRoot(document.getElementById('react-root')).render(
  <TProvider languageFiles={languageFiles}>
    <Root />
  </TProvider>,
);

Usage #

Here's an example of basic usage:

import T from '@wojtekmaj/react-t';

function MyComponent() {
  return (
    <p>
      <T>Hello world!</T>
    </p>
  );
}

How the locale is detected? #

React-T detects locale to use by going through the list of possible sources:

1. locale prop provided to <TProvider />
2. <html lang="…"> attribute
3. List of preferred user locales obtained using get-user-locale

On each step, React-T checks if a given locale is supported (provided in languageFiles, or defined as defaultLocale). If a given locale is supported, it'll use it. If not, it'll move to the next step on the list.

If no supported locale is detected, defaultLocale is used (no translation is being made).

User guide #

Usage of TProvider component #

Wrap your app in <TProvider />.

Define languageFiles prop that contains an object of:

• functions that return promises:

  {
    'de-DE': () => import('./myLanguageFile.json'),
  }
  

• functions that return language files:

  {
    'de-DE': () => myLanguageFile,
  }
  

• language files:

  {
    'de-DE': myLanguageFile,
  }
  

Usage of the T component: #

Define translatable string in the code using <T> tag:

<T>Original phrase</T>

If necessary, you may use variables like so:

<T name={name}>{'Hello, {name}'}</T>

Usage of the useTranslation hook #

Define translatable string in the code using useTranslation hook:

const translatedPhrase = useTranslation('Original phrase');

If necessary, you may use variables like so:

const translatedPhrase = useTranslation('Hello, {name}', { name });

Translating strings #

2. If you're a translator, add a corresponding entry in language JSON files, for example:

{
  "Hello world!": "Hallo Welt!"
}

If a corresponding entry in language file for current locale is not found, default locale will be used.

License #

The MIT License.

Author #

Wojciech Maj kontakt@wojtekmaj.pl https://wojtekmaj.pl