30 | {% endhint %}
31 |
32 | {% hint style="success" %}
33 | [Here](https://locize.com/blog/react-i18next/) you'll find a simple tutorial on how to best use react-i18next.\
34 | Some basics of i18next and some cool possibilities on how to optimize your localization workflow.[\
35 | .jpg)
](https://locize.com/blog/react-i18next/)
36 | {% endhint %}
37 |
38 | {% hint style="info" %}
39 | **Using Next.js?**\
40 | [Here](https://locize.com/blog/next-i18next/) you'll find a blog post on how to best use [next-i18next](https://github.com/i18next/next-i18next) with [client side translation download](https://github.com/i18next/next-i18next#client-side-loading-of-translations-via-http) and SEO optimization.
41 |
42 | [](https://locize.com/blog/next-i18next/)\
43 | \
44 | **Using Next.js with the new App Router?**\
45 | Then [this article](https://www.locize.com/blog/i18n-next-app-router) is what you are looking for!
46 |
47 | [](https://www.locize.com/blog/i18n-next-app-router)
48 | {% endhint %}
49 |
50 | {% hint style="info" %}
51 | **Using Remix?**\
52 | [Here](https://github.com/locize/locize-remix-i18next-example) you'll find a simple example and [here a step by step tutorial](https://locize.com/blog/remix-i18n/) on how to best use remix-i18next.
53 |
54 | [](https://locize.com/blog/remix-i18n/)
55 | {% endhint %}
56 |
57 | {% hint style="info" %}
58 | **Using Gatsby?**\
59 | [Here](https://github.com/locize/locize-gatsby-example) you can find an example and an appropriate [blog post](https://locize.com/blog/gatsby-i18n/).
60 |
61 | [](https://locize.com/blog/gatsby-i18n/)
62 | {% endhint %}
63 |
64 | ## What does my code look like
65 |
66 | **Before:** Your React code would have looked something like:
67 |
68 | ```jsx
69 | ...
70 | 
](https://locize.com/blog/next-i18n-static/)
29 |
30 | ## Using [Remix](https://remix.run)?
31 |
32 | You should have a look at [remix-i18next](https://github.com/sergiodxa/remix-i18next) which extends react-i18next to bring it to Remix the easiest way.
33 |
34 | > [Here](https://github.com/locize/locize-remix-i18next-example) you'll find a simple example and [here a step by step tutorial](https://locize.com/blog/remix-i18n/) on how to best use remix-i18next.
35 | >
36 | > [](https://locize.com/blog/remix-i18n/)
37 |
38 | ## Using [Gatsby](https://www.gatsbyjs.com/)?
39 |
40 | You should have a look at [gatsby-plugin-react-i18next](https://github.com/microapps/gatsby-plugin-react-i18next) which extends react-i18next to bring it to Gatsby the easiest way.
41 |
42 | > [Here](https://github.com/locize/locize-gatsby-example) you'll find a simple example and [here a step by step tutorial](https://locize.com/blog/gatsby-i18n/) on how to best use [gatsby-plugin-react-i18next](https://github.com/microapps/gatsby-plugin-react-i18next).
43 | >
44 | > [](https://locize.com/blog/gatsby-i18n/)
45 |
46 | ## Setting the i18next instance based on req
47 |
48 | Use the [I18nextProvider](i18nextprovider.md) to inject the i18next instance for example bound to the http i18n instance on the request object using [i18next-http-middleware](https://github.com/i18next/i18next-http-middleware).
49 |
50 | ```jsx
51 | and others (v10.4.0) 158 | 159 | There are two options that allow you to have basic HTML tags inside your translations, instead of numeric indexes. However, this only works for elements without additional attributes (like `className`), having none or a single text children. 160 | 161 | Examples of elements that will be readable in translation strings: 162 | 163 | * `
` 164 | * `bold` 165 | * `
some paragraph
` 166 | 167 | Examples that will be converted to indexed nodes: 168 | 169 | * ``: no attributes allowed 170 | * `{{name}}`: only text nodes allowed 171 | * `bold italic`: no nested elements, even simple ones 172 | 173 | ```jsx 174 |would be
fine 181 |
would be
fine" 183 | ``` 184 | 185 | Here is what can be configured in `i18next.options.react` that affect this behaviour: 186 | 187 | | Option | Default | Description | 188 | | ------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 189 | | `transSupportBasicHtmlNodes` | `true` | Enables keeping the name of simple nodes (e.g. `
`) in translations instead of indexed keys | 190 | | `transKeepBasicHtmlNodesFor` | `['br', 'strong', 'i', 'p']` | Which nodes are allowed to be kept in translations during `defaultValue` generation of `
-
237 | {['rupert', 'max'].map(dog => (
- {dog} ))} 238 |
If you prefer to use text as keys you can omit this, and the translation will be used as key. Can contain the namespace by prepending it in the form 'ns:key' (depending on i18next.options.nsSeparator)
But this is not recommended when used in combination with natural language keys, better use the dedicated ns parameter: <Trans i18nKey="myKey" ns="myNS"></Trans>
and simple html elements in translations 339 | transKeepBasicHtmlNodesFor: ['br', 'strong', 'i'], // don't convert to <1> if simple react elements 340 | transWrapTextNodes: '', // Wrap text nodes in a user-specified element. 341 | // i.e. set it to 'span'. By default, text nodes are not wrapped. 342 | // Can be used to work around a well-known Google Translate issue with React apps. See: https://github.com/facebook/react/issues/11538 343 | // (v11.10.0) 344 | } 345 | }); 346 | ``` 347 | 348 | {% hint style="warning" %} 349 | Please be aware if you are using **React 15 or below**, you are required to set the `defaultTransParent` option, or pass a `parent` via props. 350 | {% endhint %} 351 | 352 | {% hint style="danger" %} 353 | **Are you having trouble when your website is ran through Google Translate?**\ 354 | Google Translate seems to manipulate the DOM and makes React quite unhappy!\ 355 | **There's a work around:** you can wrap text nodes with`` using `transWrapTextNodes: 'span'`. 356 | 357 | _If you want to know more about the Google Translate issue with React, have a look at_ [_this_](https://github.com/facebook/react/issues/11538#issuecomment-390386520)_._ 358 | {% endhint %} 359 | -------------------------------------------------------------------------------- /latest/translation-render-prop.md: -------------------------------------------------------------------------------- 1 | # Translation (render prop) 2 | 3 | ## What it does 4 | 5 | The `Translation` is a render prop and gets the `t` function and `i18n` instance to your component. 6 | 7 | ```jsx 8 | import React from 'react'; 9 | import { Translation } from 'react-i18next'; 10 | 11 | export function MyComponent() { 12 | return ( 13 |
{t('my translated text')}
16 | } 17 |{t('my translated text')}
// will be looked up from namespace ns1 46 | } 47 |{t('my translated text')}
// will be looked up from namespace ns1 54 | } 55 |{t('my translated text')}
// will be looked up from namespace ns1 69 | } 70 |{t('my translated text')}
16 | } 17 | ``` 18 | 19 | While most of the time you only need the `t` function to translate your content, you can also get the i18n instance (in order to change the language). 20 | 21 | ```javascript 22 | i18n.changeLanguage('en-US'); 23 | ``` 24 | 25 | {% hint style="info" %} 26 | The `useTranslation` hook will trigger a [Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html) if not ready (eg. pending load of translation files). You can set `useSuspense` to false if prefer not using Suspense. 27 | {% endhint %} 28 | 29 | ## When to use? 30 | 31 | Use the `useTranslation` hook inside your **functional components** to access the translation function or i18n instance. 32 | 33 | {% hint style="success" %} 34 | In [this tutorial](https://locize.com/blog/react-i18next/) you'll find some ways on how to use this useTranslation hook. 35 | 36 | You'll also see how to use it when you need to work with [multiple namespaces](https://locize.com/blog/react-i18next/#multiple-namespaces).[\ 37 |.jpg)
](https://locize.com/blog/react-i18next/)
38 | {% endhint %}
39 |
40 | ## useTranslation params
41 |
42 | ### Loading namespaces
43 |
44 | ```javascript
45 | // load a specific namespace
46 | // the t function will be set to that namespace as default
47 | const { t, i18n } = useTranslation('ns1');
48 | t('key'); // will be looked up from namespace ns1
49 |
50 | // load multiple namespaces
51 | // the t function will be set to first namespace as default
52 | const { t, i18n } = useTranslation(['ns1', 'ns2', 'ns3']);
53 | t('key'); // will be looked up from namespace ns1
54 | t('key', { ns: 'ns2' }); // will be looked up from namespace ns2
55 | ```
56 |
57 | ### Overriding the i18next instance
58 |
59 | ```javascript
60 | // passing in an i18n instance
61 | // use only if you do not like the default instance
62 | // set by i18next.use(initReactI18next) or the I18nextProvider
63 | import i18n from './i18n';
64 | const { t, i18n } = useTranslation('ns1', { i18n });
65 | ```
66 |
67 | ### Optional keyPrefix option
68 |
69 | > available in react-i18next version >= 11.12.0
70 | >
71 | > depends on i18next version >= 20.6.0
72 |
73 | ```javascript
74 | // having JSON in namespace "translation" like this:
75 | /*{
76 | "very": {
77 | "deeply": {
78 | "nested": {
79 | "key": "here"
80 | }
81 | }
82 | }
83 | }*/
84 | // you can define a keyPrefix to be used for the resulting t function
85 | const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });
86 | const text = t('key'); // "here"
87 | ```
88 |
89 | {% hint style="warning" %}
90 | Do **not** use the `keyPrefix` option if you want to use keys with prefixed namespace notation:
91 |
92 | i.e.
93 |
94 | ```javascript
95 | const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });
96 | const text = t('ns:key'); // this will not work
97 | ```
98 | {% endhint %}
99 |
100 | ### Optional lng option
101 |
102 | > available in react-i18next version >= 12.3.1
103 |
104 | ```javascript
105 | // you can pass a language to be used for the resulting t function
106 | const { t } = useTranslation('translation', { lng: 'de' });
107 | const text = t('key'); // "hier"
108 | ```
109 |
110 | ### Not using Suspense
111 |
112 | ```javascript
113 | // additional ready will state if translations are loaded or not
114 | const { t, i18n, ready } = useTranslation('ns1', { useSuspense: false });
115 | ```
116 |
117 | {% hint style="info" %}
118 | Not using Suspense you will need to handle the not ready state yourself by eg. render a loading component as long `!ready` . Not doing so will result in rendering your translations before they loaded which will cause save missing be called although translations exists (just yet not loaded).
119 | {% endhint %}
120 |
--------------------------------------------------------------------------------
/latest/using-with-hooks.md:
--------------------------------------------------------------------------------
1 | # Step by step guide
2 |
3 | ## Install needed dependencies
4 |
5 | We expect you to have an existing react application supporting [hooks](https://reactjs.org/docs/hooks-intro.html) (at least v16.7.0-alpha of react and react-dom).
6 |
7 | Install both react-i18next and i18next packages:
8 |
9 | ```bash
10 | npm install react-i18next i18next --save
11 |
12 | # if you'd like to detect user language and load translation
13 | npm install i18next-http-backend i18next-browser-languagedetector --save
14 | ```
15 |
16 | ### Configure i18next
17 |
18 | I18next is the core of the i18n functionality while react-i18next extends and glues it to react.
19 |
20 | Create a new file `i18n.js` beside your `index.js` containing following content:
21 |
22 | ```javascript
23 | import i18n from 'i18next';
24 | import { initReactI18next } from 'react-i18next';
25 |
26 | import Backend from 'i18next-http-backend';
27 | import LanguageDetector from 'i18next-browser-languagedetector';
28 | // don't want to use this?
29 | // have a look at the Quick start guide
30 | // for passing in lng and translations on init
31 |
32 | i18n
33 | // load translation using http -> see /public/locales (i.e. https://github.com/i18next/react-i18next/tree/master/example/react/public/locales)
34 | // learn more: https://github.com/i18next/i18next-http-backend
35 | // want your translations to be loaded from a professional CDN? => https://github.com/locize/react-tutorial#step-2---use-the-locize-cdn
36 | .use(Backend)
37 | // detect user language
38 | // learn more: https://github.com/i18next/i18next-browser-languageDetector
39 | .use(LanguageDetector)
40 | // pass the i18n instance to react-i18next.
41 | .use(initReactI18next)
42 | // init i18next
43 | // for all options read: https://www.i18next.com/overview/configuration-options
44 | .init({
45 | fallbackLng: 'en',
46 | debug: true,
47 |
48 | interpolation: {
49 | escapeValue: false, // not needed for react as it escapes by default
50 | }
51 | });
52 |
53 |
54 | export default i18n;
55 | ```
56 |
57 | 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.
58 |
59 | Then import that in `index.js`:
60 |
61 | ```javascript
62 | import React, { Component } from "react";
63 | import { createRoot } from 'react-dom/client';
64 | import App from './App';
65 |
66 | // import i18n (needs to be bundled ;))
67 | import './i18n';
68 |
69 | const root = createRoot(document.getElementById('root'));
70 | root.render(
71 | {t('Welcome to React')}
99 | } 100 | 101 | // i18n translations might still be loaded by the http backend 102 | // use react's Suspense 103 | export default function App() { 104 | return ( 105 |{t('Welcome to React')}
158 | ) 159 | } 160 | } 161 | const MyComponent = withTranslation()(LegacyComponentClass) 162 | 163 | // i18n translations might still be loaded by the http backend 164 | // use react's Suspense 165 | export default function App() { 166 | return ( 167 |{t('my translated text')}
13 | } 14 | 15 | export default withTranslation()(MyComponent); 16 | ``` 17 | 18 | While you most time only need the t function to translate your content you also get the i18n instance to eg. change the language. 19 | 20 | ```javascript 21 | i18n.changeLanguage('en-US'); 22 | ``` 23 | 24 | {% hint style="info" %} 25 | The `withTranslation` HOC will trigger a [Suspense](https://reactjs.org/docs/code-splitting.html#suspense) if not ready (eg. pending load of translation files). You can set `useSuspense` to false if prefer not using Suspense. 26 | {% endhint %} 27 | 28 | ## When to use? 29 | 30 | Use the `withTranslation` HOC to wrap **any component (class or function)** to access the translation function or i18n instance. 31 | 32 | ## withTranslation params 33 | 34 | ### Loading namespaces 35 | 36 | ```javascript 37 | // load a specific namespace 38 | // the t function will be set to that namespace as default 39 | withTranslation('ns1')(MyComponent); 40 | 41 | // inside your component MyComponent 42 | this.props.t('key'); // will be looked up from namespace ns1 43 | 44 | // load multiple namespaces 45 | // the t function will be set to first namespace as default 46 | withTranslation(['ns1', 'ns2', 'ns3'])(MyComponent); 47 | 48 | // inside your component MyComponent 49 | this.props.t('key'); // will be looked up from namespace ns1 50 | this.props.t('key', { ns: 'ns2' }); // will be looked up from namespace ns2 51 | ``` 52 | 53 | ### Overriding the i18next instance 54 | 55 | ```javascript 56 | // passing in an i18n instance 57 | // use only if you do not like the default instance 58 | // set by i18next.use(initReactI18next) or the I18nextProvider 59 | import i18n from './i18n'; 60 | 61 | const ExtendedComponent = withTranslation('ns1')(MyComponent); 62 | 63 |{this.props.t('My translated text')}
142 | }
143 | }
144 |
145 | interface IProps extends WithTranslation {
146 | prop: any;
147 | }
148 |
149 | interface IState {
150 | state: any;
151 | }
152 |
153 | export default withTranslation()(MyComponent);
154 | ```
155 |
--------------------------------------------------------------------------------
/legacy-v9/i18next-instance.md:
--------------------------------------------------------------------------------
1 | # i18next instance (v9)
2 |
3 | The instance is an initialized i18next instance. In the following code snippet, we add a backend to load translations from server and a language detector for detecting user language.
4 |
5 | > You can learn more about [i18next](http://i18next.com) and [plugins](https://www.i18next.com/plugins-and-utils.html#plugins) on the i18next website.
6 |
7 | {% hint style="info" %}
8 | The instance could be passed to the [I18nextProvider](i18nextprovider.md) or directly to the [translate hoc](broken-reference).
9 |
10 | The **reactI18nextModule** used below is an alternative to using the [I18nextProvider](i18nextprovider.md) and asserts that components ([render prop](broken-reference), [hoc](broken-reference)) lower in the element tree get access to the i18n instance.
11 | {% endhint %}
12 |
13 | ```javascript
14 | import i18n from 'i18next';
15 | import XHR from 'i18next-xhr-backend';
16 | import LanguageDetector from 'i18next-browser-languagedetector';
17 | import { reactI18nextModule } from 'react-i18next';
18 |
19 |
20 | i18n
21 | .use(XHR)
22 | .use(LanguageDetector)
23 | .use(reactI18nextModule) // if not using I18nextProvider
24 | .init({
25 | fallbackLng: 'en',
26 | debug: true,
27 |
28 | interpolation: {
29 | escapeValue: false, // not needed for react!!
30 | },
31 |
32 | // react i18next special options (optional)
33 | react: {
34 | wait: false,
35 | bindI18n: 'languageChanged loaded',
36 | bindStore: 'added removed',
37 | nsMode: 'default'
38 | }
39 | });
40 |
41 |
42 | export default i18n;
43 | ```
44 |
45 | All additional options for react in init options:
46 |
47 | | _**options**_ | _**default**_ | _**description**_ |
48 | | ------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
49 | | wait | false | assert all provided namespaces are loaded before rendering the component (can be set [globally](i18next-instance.md) too); note that rendering will not be blocked again when dynamically updating `ns` on the [render prop component](broken-reference) after initial mount |
50 | | nsMode | 'default' | _default:_ namespaces will be loaded an the first will be set as default or _fallback:_ namespaces will be used as fallbacks used in order provided |
51 | | bindI18n | 'languageChanged loaded' | which events trigger a rerender, can be set to false or string of events |
52 | | bindStore | 'added removed' | which events on store trigger a rerender, can be set to false or string of events |
53 |
54 | For more initialization options have look at the [docs](https://www.i18next.com/configuration-options.html).
55 |
--------------------------------------------------------------------------------
/legacy-v9/i18nextprovider.md:
--------------------------------------------------------------------------------
1 | # I18nextProvider (v9)
2 |
3 | The provider is responsible to pass the i18next instance passed in by props down to all the [withNamespaces](withnamespaces.md) hocs or [NamespacesConsumer](namespacesconsumer.md) render prop using react context api.
4 |
5 | ```javascript
6 | import React from 'react';
7 | import ReactDOM from 'react-dom';
8 | import { I18nextProvider } from 'react-i18next';
9 |
10 | import App from './App'; // your entry page
11 | import i18n from './i18n'; // initialized i18next instance
12 |
13 | ReactDOM.render(
14 |
32 |
40 | )
41 | }
42 | ```
43 |
44 | You can use [formatting](https://www.i18next.com/formatting.html) as in i18next.
45 |
46 | **props**:
47 |
48 | * i18nKey: the key to lookup
49 | * options: [options](http://i18next.com/docs/options/#t-options) to use for translation (exclude interpolation variables!)
50 | * parent: optional component to wrap translation into (default 'span')
51 | * useDangerouslySetInnerHTML: allows use of raw html tags in translation values
52 | * dangerouslySetInnerHTMLPartElement: optional component to wrap parts of translation values into (default 'span'), used with `useDangerouslySetInnerHTML={true}` only
53 | * i18n: i18next instance to use if not provided via context (using hoc or render props)
54 | * t: t function to use if not provided via context (using hoc or render props)
55 | * ...props: values to interpolate into found translation (eg. `my value with {{replaceMe}} interpolation`)
56 |
57 | ## using useDangerouslySetInnerHtml
58 |
59 | Allows having html tags inside the translation with a restriction as those get wrapped in spans. You can't have a interpolation value inside a html tag.
60 |
61 | the key:
62 |
63 | ```javascript
64 | {
65 | "interpolateSample": "you can interpolate {{value}} or {{component}} via interpolate component!"
66 | }
67 | ```
68 |
69 | sample:
70 |
71 | ```javascript
72 | import React from 'react';
73 | import { translate, Interpolate } from 'react-i18next';
74 |
75 | function TranslatableView(props) {
76 | const { t } = props;
77 |
78 | let interpolateComponent = a interpolated component;
79 |
80 | return (
81 |
82 |
90 | )
91 | }
92 | ```
93 |
94 | ## Alternatives
95 |
96 | a) Use standard interpolation of i18next and dangerously insert that:
97 |
98 | ```javascript
99 |
100 | ```
101 |
102 | b) use markdown, eg. [react-remarkable](https://github.com/acdlite/react-remarkable) and pass markdown formatted content from translations to the markdown component.
103 |
--------------------------------------------------------------------------------
/legacy-v9/namespacesconsumer.md:
--------------------------------------------------------------------------------
1 | # NamespacesConsumer (v9)
2 |
3 | {% hint style="info" %}
4 | Was introduced in v8.0.0. Not available in older versions.
5 | {% endhint %}
6 |
7 | The NamespacesConsumer is a so called render prop. The component passes the [**t** function](https://www.i18next.com/overview/api#t) to child function and triggers loading the translation files defined. Further it asserts the component gets rerendered on language change or on changes to the translations themselves.
8 |
9 | {% hint style="info" %}
10 | To learn more about using the **t** function have a look at i18next documentation:
11 |
12 | * [essentials](https://www.i18next.com/translation-function/essentials)
13 | * [interpolation](https://www.i18next.com/translation-function/interpolation)
14 | * [formatting](https://www.i18next.com/translation-function/formatting)
15 | * [plurals](https://www.i18next.com/translation-function/plurals)
16 | * ...
17 | {% endhint %}
18 |
19 | ## Sample usage
20 |
21 | ```javascript
22 | import React from 'react';
23 | import { NamespacesConsumer } from 'react-i18next';
24 |
25 | function TranslatableView() {
26 | return (
27 |
34 |
37 | )
38 | }
39 | {t('keyFromDefault')}
35 |{t('anotherNamespace:key.from.another.namespace', { /* options t options */ })}
36 |assert all provided namespaces are loaded before rendering the component (can be set globally too).
Note that rendering will not be blocked again when dynamically updating the ns prop after initial mount.
In most cases you like to set this to true. If not handling not ready by evaluating ready.
| 49 | | nsMode | string ('default') |default: namespaces will be loaded and the first will be set as default
fallback: namespaces will be used as fallbacks used in order provided
{t('key')}
37 | } 38 |{t('Welcome to React')}
87 | } 88 | 89 | export default withNamespaces()(App); 90 | ``` 91 | 92 | ## 1) Adding more languages 93 | 94 | ### a) Add an additional language file 95 | 96 | **translation.json** (/public/locales/**de**/translation.json) 97 | 98 | ```javascript 99 | { 100 | "Welcome to React": "Willkommen bei react und react-i18next" 101 | } 102 | ``` 103 | 104 | ### b) Add the additional translations on init 105 | 106 | in i18n.js: 107 | 108 | ```javascript 109 | // ... 110 | import translationEN from '../public/locales/en/translation.json'; 111 | import translationDE from '../public/locales/de/translation.json'; 112 | 113 | // the translations 114 | const resources = { 115 | en: { 116 | translation: translationEN 117 | }, 118 | de: { 119 | translation: translationDE 120 | } 121 | }; 122 | 123 | // ... 124 | ``` 125 | 126 | ### c) Auto detect the user language 127 | 128 | As the language is set on `i18n.init` you either could create some custom code setting the needed language or just use one of the provided language detectors coming with i18next. 129 | 130 | For browser usage there is the [i18next-browser-languageDetector](https://github.com/i18next/i18next-browser-languageDetector) which detects language based on: 131 | 132 | * cookie 133 | * localStorage 134 | * navigator 135 | * querystring (append `?lng=LANGUAGE` to URL) 136 | * htmlTag 137 | * path 138 | * subdomain 139 | 140 | ```bash 141 | npm install i18next-browser-languagedetector --save 142 | ``` 143 | 144 | Using it before i18n.init is all needed to get this to work: 145 | 146 | ```javascript 147 | import i18n from "i18next"; 148 | import detector from "i18next-browser-languagedetector"; 149 | import { reactI18nextModule } from "react-i18next"; 150 | 151 | import translationEN from '../public/locales/en/translation.json'; 152 | import translationDE from '../public/locales/de/translation.json'; 153 | 154 | // the translations 155 | const resources = { 156 | en: { 157 | translation: translationEN 158 | }, 159 | de: { 160 | translation: translationDE 161 | } 162 | }; 163 | 164 | i18n 165 | .use(detector) 166 | .use(reactI18nextModule) // passes i18n down to react-i18next 167 | .init({ 168 | resources, 169 | fallbackLng: "en", // use en if detected lng is not available 170 | 171 | keySeparator: false, // we do not use keys in form messages.welcome 172 | 173 | interpolation: { 174 | escapeValue: false // react already safes from xss 175 | } 176 | }); 177 | 178 | export default i18n; 179 | ``` 180 | 181 | Now we already are able to set language based on the browsers set language or by appending `?lng=LANGUAGE` to the URL. 182 | 183 | ### d) Let the user toggle the language 184 | 185 | Call [i18n.changeLanguage](https://www.i18next.com/overview/api#changelanguage) is all needed to do. 186 | 187 | ```jsx 188 | import React from 'react'; 189 | import i18n from './i18n'; 190 | import { withNamespaces } from 'react-i18next'; 191 | 192 | function App ({ t }) { 193 | const changeLanguage = (lng) => { 194 | i18n.changeLanguage(lng); 195 | } 196 | 197 | return ( 198 |
199 |
200 |
201 |
203 | )
204 | }
205 |
206 | export default withNamespaces()(App);
207 | ```
208 |
209 | {% hint style="info" %}
210 | It's essential to have at least your outer page level / container component wrapped with the [withNamespaces](withnamespaces.md) or [NamespacesConsumer](namespacesconsumer.md) as those are bound to the [languageChanged event](https://www.i18next.com/overview/api#onlanguagechanged) and trigger a needed rerender.
211 | {% endhint %}
212 |
213 | ## 2) Lazy loading translations
214 |
215 | We haven't yet started splitting translations into multiple files (which is highly recommended for larger projects) but we already see that adding more languages would result in bundling unneeded translations into the application.
216 |
217 | > Why not just use dynamic imports to load the language needed?
218 |
219 | This for sure works but comes with one drawback. If you have a change in your translations you will need to rebuild your application and deploy that.
220 |
221 | This might not be a problem when starting but at some point you will learn localization is a complete different beast than just adding i18n to your code. You will keep translations as separated from your code as you can - so developers and translators can work as independent as possible.
222 |
223 | ### a) Adding lazy loading for translations
224 |
225 | This will be simpler than you think. All needed to be done is adding another package called [i18next-http-backend](https://github.com/i18next/i18next-http-backend) and using that.
226 |
227 | ```bash
228 | npm install i18next-http-backend --save
229 | ```
230 |
231 | **i18n.js**
232 |
233 | ```javascript
234 | import i18n from "i18next";
235 | import detector from "i18next-browser-languagedetector";
236 | import backend from "i18next-http-backend";
237 | import { reactI18nextModule } from "react-i18next";
238 |
239 | // translations are already at
240 | // '../public/locales/en/translation.json'
241 | // which is the default for the xhr backend to load from
242 |
243 | i18n
244 | .use(detector)
245 | .use(backend)
246 | .use(reactI18nextModule) // passes i18n down to react-i18next
247 | .init({
248 | fallbackLng: "en", // use en if detected lng is not available
249 |
250 | keySeparator: false, // we do not use keys in form messages.welcome
251 |
252 | interpolation: {
253 | escapeValue: false // react already safes from xss
254 | }
255 | });
256 |
257 | export default i18n;
258 | ```
259 |
260 | {% hint style="info" %}
261 | i18next implementation is smart enough to only load needed languages and comes with intelligent deduplications so even multiple load requests for files in different code locations result in one request while notifying all needed requester.
262 | {% endhint %}
263 |
264 | ### b) Loading multiple translation files
265 |
266 | Lets assume your project started to grow and you like to split translations into multiple files.
267 |
268 | Without configuration i18next will always load one file (namespace) named `translation`. Learn more about namespaces [here](https://www.i18next.com/principles/namespaces).
269 |
270 | You can load them on i18n.init or in code like:
271 |
272 | ```javascript
273 | i18n.init({
274 | ns: ['common', 'moduleA', 'moduleB'],
275 | defaultNS: 'moduleA'
276 | }, (err, t) => {
277 | i18n.t('myKey'); // key in moduleA namespace (defined default)
278 | i18n.t('common:myKey'); // key in common namespace
279 | });
280 |
281 | // load additional namespaces after initialization
282 | i18n.loadNamespaces('anotherNamespace', (err, t) => { /* ... */ });
283 | ```
284 |
285 | But that will load all upfront or in some custom code where you would need to handle manually that the translations were loaded. So there is a better way.
286 |
287 | #### Use the withNamespaces hoc
288 |
289 | As you might guess the withNamespaces hocs role is to lazy load the needed namespaces.
290 |
291 | **page2.json Add more translation files:** (/public/locales/en/page2.json)
292 |
293 | ```javascript
294 | {
295 | "Welcome on page2": "Welcome on page2"
296 | }
297 | ```
298 |
299 | **Page2.js** (/src/Page2.js)
300 |
301 | ```jsx
302 | import React from 'react';
303 |
304 | // the hoc
305 | import { withNamespaces } from 'react-i18next';
306 |
307 | function Page2 ({ t }) {
308 | return {t('Welcome to React')}
202 |{t('Welcome on page2')}
309 | } 310 | 311 | export default withNamespaces('page2')(Page2); 312 | ``` 313 | 314 | ### c) Handle rendering while translations are not yet loaded 315 | 316 | In the above `Page2` you will notice the initial render will trigger the load for `page2.json` but also render the page without the translations ready. There will be a rerender when the translations where loaded resulting in the page flickering. 317 | 318 | #### Using the prop tReady 319 | 320 | tReady will be set to true when translations are loaded so you can eg. suspend rendering and show a Spinner or another placeholder: 321 | 322 | ```jsx 323 | import React from 'react'; 324 | 325 | // the hoc 326 | import { withNamespaces } from 'react-i18next'; 327 | 328 | function Page2 ({ t, tReady }) { 329 | // just to add some more here we load an additional namespace 330 | // common for "common" used texts and use that namespace 331 | // be prefixing it in front of the key "common:" 332 | if (!tReady) return{t('common:loading')}
333 | 334 | return{t('Welcome on page2')}
335 | } 336 | 337 | export default withNamespaces(['page2', 'common'])(Page2); 338 | ``` 339 | 340 | #### Set the global wait option 341 | 342 | You can configure the withNamespaces / NamespacesConsumer to not render the content until needed namespaces are loaded. 343 | 344 | **i18n.js:** 345 | 346 | ```javascript 347 | import i18n from "i18next"; 348 | import detector from "i18next-browser-languagedetector"; 349 | import backend from "i18next-http-backend"; 350 | import { reactI18nextModule } from "react-i18next"; 351 | 352 | i18n 353 | .use(detector) 354 | .use(backend) 355 | .use(reactI18nextModule) // passes i18n down to react-i18next 356 | .init({ 357 | fallbackLng: "en", // use en if detected lng is not available 358 | 359 | keySeparator: false, // we do not use keys in form messages.welcome 360 | 361 | interpolation: { 362 | escapeValue: false // react already safes from xss 363 | }, 364 | 365 | // react-i18next options 366 | react: { 367 | wait: true 368 | } 369 | }); 370 | 371 | export default i18n; 372 | ``` 373 | 374 | Now `Page2` will be blank until the needed translation files were loaded. 375 | 376 | {% hint style="info" %} 377 | You can set the wait option either globally for all instances or individually like: 378 | 379 | `withNamepaces('page2', { wait: true })(Page2);` 380 | {% endhint %} 381 | 382 | ## 3) Sidequest: natural vs. keybased catalog 383 | 384 | ### a) natural keys 385 | 386 | Until now we had organised translation and keys in natural language. 387 | 388 | ```jsx 389 |{t('Welcome on page2')}
390 | ``` 391 | 392 | Having translation files like: 393 | 394 | ```javascript 395 | { 396 | "Welcome on page2": "Welcome on page2" 397 | } 398 | ``` 399 | 400 | This was possible by setting `keySeparator: false` on `i18n.init` 401 | 402 | The upside of this the code can be more readable but the content of the key might get soon rather different from the value it reflects. You could even go a step further by disabling any fallback language and [using the key as fallback](https://www.i18next.com/principles/fallback#key-fallback) - but be aware if you have a typo in the key acting as fallback value you will need to change it. 403 | 404 | ### b) keybased catalog 405 | 406 | Some i18n frameworks organise having more technical keys allowing those to be even structured into hierarchies. This is the default in i18next too - so removing `keySeparator: false` on `i18n.init` would enable having catalogs and `t` usage like: 407 | 408 | ```javascript 409 | { 410 | "titles": { 411 | "page2": "Welcome on page2" 412 | } 413 | } 414 | ``` 415 | 416 | accessed like: 417 | 418 | ```jsx 419 |{t('titles.page2')}
420 | ``` 421 | 422 | If you prefer natural or keybased is a matter of taste...both can be used with react-i18next. Just avoid mixing those styles. 423 | 424 | ## 4) HOCs are dead - long lives the render props 425 | 426 | We won't open a debate over which is better as in our opinion both have their use case and there is no reason to just use one of the two options. 427 | 428 | So you already saw before that you can use the [withNamespaces](withnamespaces.md) to decorate your component to pass the `t` function down. 429 | 430 | The same works with [a render prop](namespacesconsumer.md): 431 | 432 | ```jsx 433 | import React from 'react'; 434 | 435 | // the render prop 436 | import { NamespacesConsumer } from 'react-i18next'; 437 | 438 | export default function Page2 () { 439 | ( 440 |{t('Welcome on page2')}
: 445 |{t('common:loading')}
446 | ) 447 | } 448 |463 | Translating content with 464 | formatting 465 | or a 466 | link 467 | is a pain. 468 |
469 | ``` 470 | 471 | So naive approach using the `t` function would result in 472 | 473 | ```jsx 474 |475 | { t('Translating content with ') } 476 | t('formatting') 477 | { t(' or a ') } 478 | t('link') 479 | { t(' is a pain.') } 480 |
481 | ``` 482 | 483 | So you end up with 5 keys in your translation file and your translator has no idea about how these 5 keys relate to each other. Further what happens in other languages where the order needs to be changed?!? 484 | 485 | So you won't have luck with this approach. 486 | 487 | ### Using the Trans component 488 | 489 | The [Trans component](trans-component.md) enables you to keep this as one sentence by replacing the JSX nodes with indexed pseudo tags. 490 | 491 | ```jsx 492 | import { Trans } from 'react-i18next'; 493 | 494 | // ... 495 | 496 |
497 |
35 | Hello {name}, you have {count} unread message(s). Go to messages.
36 |
37 | ```
38 |
39 | **After:** With the trans component just change it to:
40 |
41 | ```javascript
42 | {t('Welcome to React')}
; 18 | } 19 | } 20 | export default withI18n()(MyComponent); 21 | ``` 22 | 23 | {% hint style="danger" %} 24 | This component won't trigger a rerender on language change. The passed down `t` function will be the same as calling `i18n.t` directly and not be bound to a specific namespace or even trigger a load of a namespace. 25 | 26 | If you do **not pass in translations** on `i18n.init` we highly encourage using the [withNamespaces](withnamespaces.md) hoc. 27 | {% endhint %} 28 | -------------------------------------------------------------------------------- /legacy-v9/withnamespaces.md: -------------------------------------------------------------------------------- 1 | # withNamespaces (v9) 2 | 3 | {% hint style="info" %} 4 | Was introduced in v8.0.0. Not available in older versions. 5 | {% endhint %} 6 | 7 | The withNamespaces [hoc](https://reactjs.org/docs/higher-order-components.html) is responsible for passing the [**t** function](https://www.i18next.com/overview/api#t) to your component. It enables all the translation functionality provided by i18next. Further, it asserts your component gets re-rendered on language change or changes to the translation catalog itself (loaded translations). 8 | 9 | ```javascript 10 | withNamespaces(namespaces, options)(MyComponent); 11 | ``` 12 | 13 | {% hint style="info" %} 14 | To learn more about using the **t** function have a look at i18next documentation: 15 | 16 | * [essentials](https://www.i18next.com/essentials.html) 17 | * [interpolation](https://www.i18next.com/interpolation.html) 18 | * [formatting](https://www.i18next.com/formatting.html) 19 | * [plurals](https://www.i18next.com/plurals.html) 20 | * ... 21 | {% endhint %} 22 | 23 | ## Sample 24 | 25 | ```javascript 26 | import React from 'react'; 27 | import { withNamespaces } from 'react-i18next'; 28 | 29 | function TranslatableView(props) { 30 | const { t, tReady } = props; 31 | // tReady is true if translations were loaded. 32 | // Use wait option to not render before loaded 33 | // or render placeholder yourself if not tReady=false 34 | 35 | return ( 36 |
37 |
40 | )
41 | }
42 |
43 | export default withNamespaces([
44 | 'defaultNamespace',
45 | 'anotherNamespace'
46 | ], { /* additional options see below */ })(TranslatableView);
47 |
48 | // or: short for only loading one namespace:
49 | export default withNamespaces('defaultNamespace')(TranslatableView);
50 |
51 | // or: short for using defaultNS defined in i18next
52 | export default withNamespaces()(TranslatableView);
53 |
54 | // or: using a function to return namespaces based on props
55 | export default withNamespaces((props) => props.namespaces)(TranslatableView);
56 | ```
57 |
58 | If not using the [reactI18nextModule](i18next-instance.md) this hoc should be nested inside a [I18nextProvider](i18nextprovider.md). Alternatively you can pass the i18next instance via prop `i18n`.
59 |
60 | ## Using with TypeScript
61 |
62 | To help you using TypeScript and the @withNamespaces decorator here is a trival example:
63 |
64 | ```jsx
65 | import * as React from 'react';
66 | import { withNamespaces, WithNamespaces } from 'react-i18next';
67 |
68 | class MyComponent extends React.PureComponent{t('keyFromDefault')}
38 |{t('anotherNamespace:key.from.another.namespace', { /* options t options */ })}
39 |assert all provided namespaces are loaded before rendering the component (can be set globally too)
In most cases you like to set this to true. If not handling not ready by evaluating tReady.
| 114 | | nsMode | string ('default') |default: namespaces will be loaded an the first will be set as default or
fallback: namespaces will be used as fallbacks used in order provided
| 115 | | innerRef | function or object (undefined) |either pass in a object React.createRef or a ref function like (c) => this.myRef = c;
| 116 | | bindI18n | string ('languageChanged loaded') | which events trigger a rerender, can be set to false or string of events | 117 | | bindStore | string ('added removed') | which events on store trigger a rerender, can be set to false or string of events | 118 | | omitBoundRerenders | boolean (true) | Does not trigger rerenders while state not ready - avoiding unneeded renders on init | 119 | | i18n | object (undefined) | pass i18next via options (useful for [next.js usage](https://github.com/i18next/react-i18next/tree/v9.x.x/example/nextjs) | 120 | | usePureComponent | boolean (false) | use shallowEqual on props change if set to true | 121 | 122 | ## withNamespaces props: 123 | 124 | | _**name**_ | _**type (default)**_ | _**description**_ | 125 | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | 126 | | i18n | object (undefined) | pass i18next instance by props instead of having it on context | 127 | | initialI18nStore | object (undefined) | pass in initial translations (useful for [next.js usage](https://github.com/i18next/react-i18next/tree/v9.x.x/example/nextjs)) | 128 | | initialLanguage | object (undefined) | pass in initial language (useful for [next.js usage](https://github.com/i18next/react-i18next/tree/v9.x.x/example/nextjs)) | 129 | -------------------------------------------------------------------------------- /methods.md: -------------------------------------------------------------------------------- 1 | # Defining Methods 2 | 3 | Methods allow you to smoothly display code examples in different languages. 4 | 5 | {% method %} 6 | ## My first method 7 | 8 | My first method exposes how to print a message in JavaScript and Go. 9 | 10 | {% sample lang="js" %} 11 | Here is how to print a message to `stdout` using JavaScript. 12 | 13 | ```js 14 | console.log('My first method'); 15 | ``` 16 | 17 | {% sample lang="go" %} 18 | Here is how to print a message to `stdout` using Go. 19 | 20 | ```go 21 | fmt.Println("My first method") 22 | ``` 23 | 24 | {% common %} 25 | Whatever language you are using, the result will be the same. 26 | 27 | ```bash 28 | $ My first method 29 | ``` 30 | {% endmethod %} 31 | -------------------------------------------------------------------------------- /misc/testing.md: -------------------------------------------------------------------------------- 1 | # Testing 2 | 3 | For testing purpose of your component you should export the pure component without extending with the withTranslation hoc and test that: 4 | 5 | ```javascript 6 | export MyComponent; 7 | export default withTranslation('ns')(MyComponent); 8 | ``` 9 | 10 | In the test, test the myComponent export passing a t function mock: 11 | 12 | ```javascript 13 | import { MyComponent } from './myComponent'; 14 | 15 |// implementation
70 | import React from 'react';
71 | import { useTranslation } from 'react-i18next';
72 |
73 | export default function CustomComponent() {
74 | const { t } = useTranslation();
75 |
76 | return <div>{t('some.key', { some: 'variable' })}</div>;
77 | }
78 |
79 | // test
80 | import React from 'react';
81 | import { mount } from 'enzyme';
82 | import UseTranslationWithInterpolation from './UseTranslationWithInterpolation';
83 | import { useTranslation } from 'react-i18next';
84 |
85 | jest.mock('react-i18next', () => ({
86 | useTranslation: jest.fn(),
87 | }));
88 |
89 | it('test render', () => {
90 | const useTranslationSpy = useTranslation;
91 | const tSpy = jest.fn((str) => str);
92 | useTranslationSpy.mockReturnValue({
93 | t: tSpy,
94 | i18n: {
95 | changeLanguage: () => new Promise(() => {}),
96 | },
97 | });
98 |
99 | const mounted = mount(<UseTranslationWithInterpolation />);
100 |
101 | // console.log(mounted.debug());
102 | expect(mounted.contains(<div>some.key</div>)).toBe(true);
103 |
104 | // If you want you can also check how the t function has been called,
105 | // but basically this is testing your mock and not the actual code.
106 | expect(tSpy).toHaveBeenCalledTimes(1);
107 | expect(tSpy).toHaveBeenLastCalledWith('some.key', { some: 'variable' });
108 | });
109 | {t('icu', { numPersons: 500 })}
60 | }
61 |
62 | // ...
63 |
64 | // json
65 | "icu": "{numPersons, plural, =0 {no persons} =1 {one person} other {# persons}}",
66 |
67 | // result:
68 | 500 persons
69 | ```
70 |
71 | ### using the Trans Component
72 |
73 | As is including plain ICU syntax inside a JSX node will result in invalid JSX as the ICU format uses curly brackets that are reserved by JSX.
74 |
75 | So the default option is to use the [Trans Component](../legacy-v9/trans-component.md) just with props like:
76 |
77 | ```javascript
78 | import { Trans } from 'react-i18next';
79 |
80 | const user = 'John Doe';
81 |
82 |