withNamespaces (v9)

i18next localization as a service Find your translator
Search…
withNamespaces (v9)
Was introduced in v8.0.0. Not available in older versions.
The withNamespaces hoc is responsible for passing the t function 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).
withNamespaces(namespaces, options)(MyComponent);
To learn more about using the t function have a look at i18next documentation:
​essentials​
​interpolation​
​formatting​
​plurals​
...
Sample
import React from 'react';
import { withNamespaces } from 'react-i18next';
​
function TranslatableView(props) {
  const { t, tReady } = props;
  // tReady is true if translations were loaded.
  // Use wait option to not render before loaded
  // or render placeholder yourself if not tReady=false
​
  return (
    <div>
      <h1>{t('keyFromDefault')}</h1>
      <p>{t('anotherNamespace:key.from.another.namespace', { /* options t options */ })}</p>
    </div>
  )
}
​
export default withNamespaces([
  'defaultNamespace',
  'anotherNamespace'
], { /* additional options see below */ })(TranslatableView);
​
// or: short for only loading one namespace:
export default withNamespaces('defaultNamespace')(TranslatableView);
​
// or: short for using defaultNS defined in i18next
export default withNamespaces()(TranslatableView);
​
// or: using a function to return namespaces based on props
export default withNamespaces((props) => props.namespaces)(TranslatableView);
If not using the reactI18nextModule this hoc should be nested inside a I18nextProvider. Alternatively you can pass the i18next instance via prop i18n.
Using with TypeScript
To help you using TypeScript and the @withNamespaces decorator here is a trival example:
import * as React from 'react';
import { withNamespaces, WithNamespaces } from 'react-i18next';
​
class MyComponent extends React.PureComponent<WithNamespaces> {
  public render() {
    const { t } = this.props;
    return (
      <React.Fragment>
        <span>{t('my-component-content')}</span>
      </React.Fragment>
    );
  }
}
export default withNamespaces()(MyComponent);
​
Set defaults for all used withNamespaces
Most time you like to change those values for every component.
Set those on i18next init:
i18n.init({
  // ... other options
  react: {
    wait: false,
    withRef: false,
    bindI18n: 'languageChanged loaded',
    bindStore: 'added removed',
    nsMode: 'default'
  }
});
withNamespaces options:
export default withNamespaces(
  'defaultNamespace',
  { wait: true } // <-- options
)(TranslatableView);
option
type (default)
description
wait
boolean (false)
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.
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
innerRef
function or object (undefined)
either pass in a object React.createRef or a ref function like (c) => this.myRef = c;
​
​read more​
bindI18n
string ('languageChanged loaded')
which events trigger a rerender, can be set to false or string of events
bindStore
string ('added removed')
which events on store trigger a rerender, can be set to false or string of events
omitBoundRerenders
boolean (true)
Does not trigger rerenders while state not ready - avoiding unneeded renders on init
i18n
object (undefined)
pass i18next via options (useful for next.js usage​
usePureComponent
boolean (false)
use shallowEqual on props change if set to true
withNamespaces props:
name
type (default)
description
i18n
object (undefined)
pass i18next instance by props instead of having it on context
initialI18nStore
object (undefined)
pass in initial translations (useful for next.js usage)
initialLanguage
object (undefined)
pass in initial language (useful for next.js usage)
legacy v9 - Previous
withI18n (v9)
Next - legacy v9
NamespacesConsumer (v9)
Last modified 3yr ago
Copy link
Outline
Sample
Using with TypeScript
Set defaults for all used withNamespaces
withNamespaces options:
withNamespaces props: