Step by step guide

Install needed dependencies

We expect you to have an existing react application supporting hooks (at least v16.7.0-alpha of react and react-dom).
Install both react-i18next and i18next packages:
1
npm install react-i18next i18next --save
2
3
// if you'd like to detect user language and load translation
4
npm install i18next-http-backend i18next-browser-languagedetector --save
Copied!

Configure i18next

I18next is the core of the i18n functionality while react-i18next extends and glues it to react.
Create a new file i18n.js beside your index.js containing following content:
1
import i18n from 'i18next';
2
import { initReactI18next } from 'react-i18next';
3
4
import Backend from 'i18next-http-backend';
5
import LanguageDetector from 'i18next-browser-languagedetector';
6
// don't want to use this?
7
// have a look at the Quick start guide
8
// for passing in lng and translations on init
9
10
i18n
11
// load translation using http -> see /public/locales (i.e. https://github.com/i18next/react-i18next/tree/master/example/react/public/locales)
12
// learn more: https://github.com/i18next/i18next-http-backend
13
// want your translations to be loaded from a professional CDN? => https://github.com/locize/react-tutorial#step-2---use-the-locize-cdn
14
.use(Backend)
15
// detect user language
16
// learn more: https://github.com/i18next/i18next-browser-languageDetector
17
.use(LanguageDetector)
18
// pass the i18n instance to react-i18next.
19
.use(initReactI18next)
20
// init i18next
21
// for all options read: https://www.i18next.com/overview/configuration-options
22
.init({
23
fallbackLng: 'en',
24
debug: true,
25
26
interpolation: {
27
escapeValue: false, // not needed for react as it escapes by default
28
}
29
});
30
31
32
export default i18n;
Copied!
The interesting part here is by i18n.use(initReactI18next) we pass the i18n instance to react-i18next which will make it available for all the components.
Then import that in index.js:
1
import React, { Component } from "react";
2
import ReactDOM from "react-dom";
3
import App from './App';
4
5
// import i18n (needs to be bundled ;))
6
import './i18n';
7
8
ReactDOM.render(
9
<App />,
10
document.getElementById("root")
11
);
Copied!

Translate your content

Using the useTranslation hook

You can use the hook inside your functional components like:
1
import React, { Suspense } from 'react';
2
import { useTranslation } from 'react-i18next';
3
4
function MyComponent() {
5
const { t, i18n } = useTranslation();
6
7
return <h1>{t('Welcome to React')}</h1>
8
}
9
10
// i18n translations might still be loaded by the http backend
11
// use react's Suspense
12
export default function App() {
13
return (
14
<Suspense fallback="loading">
15
<MyComponent />
16
</Suspense>
17
);
18
}
Copied!
The useTranslation hook function takes one options argument. You can either pass in a namespace or an array of namespaces to load.
1
const { t, i18n } = useTranslation('common');
2
3
const { t, i18n } = useTranslation(['page1', 'common']);
Copied!

Translation Files

Create a new file public/locales/<language_code>/translation.json with the following sample content.
1
{
2
"title": "Welcome to react using react-i18next",
3
"description": {
4
"part1": "To get started, edit <1>src/App.js</1> and save to reload.",
5
"part2": "Switch language between english and german using buttons above."
6
}
7
}
Copied!
Files are plain JSON you can checkout the full sample here.
Please note the t function will be either bound to the default namespace defined on i18next init or to the first one passed in arguments.

Using the withTranslation HOC

There might be some legacy cases where you are still forced to use classes. Don't worry, we still provide a hoc to cover these cases:
1
import React, { Component, Suspense } from 'react';
2
import { withTranslation } from 'react-i18next';
3
4
class LegacyComponentClass extends Component {
5
render() {
6
const { t } = this.props;
7
8
return (
9
<h1>{t('Welcome to React')}</h1>
10
)
11
}
12
}
13
const MyComponent = withTranslation()(LegacyComponentClass)
14
15
// i18n translations might still be loaded by the http backend
16
// use react's Suspense
17
export default function App() {
18
return (
19
<Suspense fallback="loading">
20
<MyComponent />
21
</Suspense>
22
);
23
}
Copied!
The withTranslation hook function takes one options argument. You can either pass in a namespace or a array of namespaces to load.
1
withTranslation('common')(LegacyComponentClass);
2
3
withTranslation(['page1', 'common'])(LegacyComponentClass);
Copied!

Using the Trans component

The Trans component is the best way to translate a JSX tree in one translation. This enables you to eg. easily translate text containing a link component or formatting like <strong>.
1
import React from 'react';
2
import { Trans } from 'react-i18next';
3
4
export default function MyComponent () {
5
return <Trans>Welcome to <strong>React</strong></Trans>
6
}
7
8
// the translation in this case should be
9
"Welcome to <1>React</1>": "Welcome to <1>React and react-i18next</1>"
Copied!
Don't worry if you do not yet understand how the Trans component works in detail. Learn more about it here.

See the sample

Prefer having code to checkout? Directly dive into our example:

Do you like to read a more complete step by step tutorial?

Here you'll find a simple tutorial on how to best use react-i18next. Some basics of i18next and some cool possibilities on how to optimize your localization workflow.
Last modified 29d ago