On this page
useTranslation (hook)
useTranslation gives a component its t function and the i18next instance, and renders it again when the language changes.
What it does
Call it inside a function component:
import { useTranslation } from 'react-i18next';
export function MyComponent() {
// without a namespace, it uses defaultNS ('translation' by default)
const { t, i18n } = useTranslation();
return <p>{t('welcome')}</p>;
}
Most of the time you only need t; the i18n instance is there to change the language, for example i18n.changeLanguage('en-US').
While translations are still loading, the hook suspends the component, so wrap it in React's Suspense or turn that off.
useTranslation params
Loading namespaces
// load a specific namespace; t uses it as default
const { t } = useTranslation('ns1');
t('key'); // looked up in ns1
// load several namespaces; t uses the first one as default
const { t } = useTranslation(['ns1', 'ns2', 'ns3']);
t('key'); // looked up in ns1
t('key', { ns: 'ns2' }); // looked up in ns2
Only t is bound to the namespace (through i18next's getFixedT); i18n is the plain i18next instance.
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
// translation.json: { "very": { "deeply": { "nested": { "key": "here" } } } }
const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });
const text = t('key'); // -> "here"
With a keyPrefix, keys with a namespace prefix such as t('ns:key') do not resolve.
Optional lng option
// 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
// ready says whether the translations are loaded
const { t, i18n, ready } = useTranslation('ns1', { useSuspense: false });
When not using Suspense, you will need to handle the not-ready state yourself, e.g. by rendering a loading component as long as !ready. Not doing so will result in rendering your translations before they are loaded, which will cause save missing to be called although the translations exist (just not loaded yet).
Troubleshooting
Blank screen or "suspended while rendering, but no fallback UI was specified"? useSuspense is true by default: while translations load asynchronously (http backend, ...), the component suspends. Either wrap it in a <Suspense fallback={...}> boundary, or set useSuspense: false and handle the ready flag as shown above.