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:

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;

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)

Last updated 4 months ago