useTranslation (hook)

What it does

It gets the t function and i18n instance inside your functional component.

JavaScript

import React from 'react';
import { useTranslation } from 'react-i18next';

export function MyComponent() {
  const { t, i18n } = useTranslation(); // not passing any namespace will use the defaultNS (by default set to 'translation')
  // or const [t, i18n] = useTranslation();

  return <p>{t('my translated text')}</p>
}

TypeScript

import React from 'react';
import { useTranslation } from 'react-i18next';

export function MyComponent() {
  const { t, i18n } = useTranslation(); // not passing any namespace will use the defaultNS (by default set to 'translation')
  // or const [t, i18n] = useTranslation();

  return <p>{t($ => $['my translated text'])}</p>
}

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).

i18n.changeLanguage('en-US');

The useTranslation hook will trigger a Suspense if not ready (eg. pending load of translation files). You can set useSuspense to false if prefer not using Suspense.

When to use?

Use the useTranslation hook inside your functional components to access the translation function or i18n instance.

In this tutorial you'll find some ways on how to use this useTranslation hook.

You'll also see how to use it when you need to work with multiple namespaces.

useTranslation params

Loading namespaces

JavaScript

// load a specific namespace
// the t function will be set to that namespace as default
const { t, i18n } = useTranslation('ns1');
t('key'); // will be looked up from namespace ns1

// load multiple namespaces
// the t function will be set to first namespace as default
const { t, i18n } = useTranslation(['ns1', 'ns2', 'ns3']);
t('key'); // will be looked up from namespace ns1
t('key', { ns: 'ns2' }); // will be looked up from namespace ns2

TypeScript

// load a specific namespace
// the t function will be set to that namespace as default
const { t, i18n } = useTranslation('ns1');
t('key'); // will be looked up from namespace ns1

// load multiple namespaces
// the t function will be set to first namespace as default
const { t, i18n } = useTranslation(['ns1', 'ns2', 'ns3']);
t($ => $.key); // will be looked up from namespace ns1
t($ => $.key, { ns: 'ns2' }); // will be looked up from namespace ns2

// since react-i18next v17.0.7 / i18next v26.0.10 a selector path whose first
// segment matches a *secondary* namespace is routed to that namespace too:
t($ => $.ns2.key); // will be looked up from namespace ns2
t($ => $.ns3.deep.key); // will be looked up from namespace ns3
// the primary namespace ('ns1' here) is never rewritten — `$.ns1.key` would
// mean a literal sub-key inside ns1 rather than a switch.

Only the t function is bound to the namespace, behind the scenes it uses the getFixedT function of i18next. The i18n instance is the normal i18next instance. Not bound to anything special.

Selector ns prefix vs. resolution scope. Plain t('key') calls remain isolated to the primary namespace under default nsMode — they don't fall through to the secondary namespaces. Only the selector's first segment is matched against the hook's full namespace list, via the new scopeNs argument that useTranslation now passes to getFixedT. If you want t('key') to fall through to all namespaces in order, use nsMode: 'fallback' (unchanged from before).

Overriding the i18next instance

// passing in an i18n instance
// use only if you do not like the default instance
// set by i18next.use(initReactI18next) or the I18nextProvider
import i18n from './i18n';
const { t, i18n } = useTranslation('ns1', { i18n });

Optional keyPrefix option

available in react-i18next version >= 11.12.0

depends on i18next version >= 20.6.0

JavaScript

// having JSON in namespace "translation" like this:
/*{
    "very": {
      "deeply": {
        "nested": {
          "key": "here"
        }
      }
    }
}*/
// you can define a keyPrefix to be used for the resulting t function
const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });
const text = t('key'); // "here"

TypeScript

// having JSON in namespace "translation" like this:
/*{
    "very": {
      "deeply": {
        "nested": {
          "key": "here"
        }
      }
    }
}*/
// you can define a keyPrefix to be used for the resulting t function
const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });
const text = t($ => $.key); // "here"

JavaScript

Do not use the keyPrefix option if you want to use keys with prefixed namespace notation:

i.e.

const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });
const text = t('ns:key'); // this will not work

TypeScript

Do not use the keyPrefix option if you want to use keys with prefixed namespace notation:

i.e.

const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });
const text = t($ => $.key, { ns: 'ns' }); // this will not work

Optional lng option

available in react-i18next version >= 12.3.1

JavaScript

// you can pass a language to be used for the resulting t function
const { t } = useTranslation('translation', { lng: 'de' });
const text = t('key'); // "hier"

TypeScript

// you can pass a language to be used for the resulting t function
const { t } = useTranslation('translation', { lng: 'de' });
const text = t($ => $.key); // "hier"

Not using Suspense

// additional ready will state if translations are loaded or not
const { t, i18n, ready } = useTranslation('ns1', { useSuspense: false });

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).

Troubleshooting

Blank screen or "suspended while rendering, but no fallback UI was specified"? useSuspense is true by default: while translations load asynchronously (http backend, locize backend, ...), the component suspends. Either wrap it in a <Suspense fallback={...}> boundary, or set useSuspense: false and handle the ready flag as shown above. Since v17.0.10 a development-only console warning points this out when it happens.

"Rendered more hooks than during the previous render" pointing at useTranslation? This was a bug in react-i18next < 16.3 (an early return before all hooks ran when the i18next instance wasn't ready yet, typically under init/render races or React StrictMode). It is fixed in >= 16.3; upgrade instead of working around it.