React-T
Simple translation module for React applications.
tl;dr
- Install by executing
npm install @wojtekmaj/react-toryarn 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:
and adding
{ "Hello world!": "Hallo Welt!" }languageFilesto<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:
-
localeprop provided to<TProvider /> -
<html lang="…">attribute - 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
- 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 |