Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
useTranslation
✓ import { useTranslation } from 'react-i18next';
✗ const { useTranslation } = require('react-i18next');
This hook is the primary way to access translation functions and i18n instance in functional components since v10. Not available in CommonJS.
Trans
✓ import { Trans } from 'react-i18next';
✗ import Trans from 'react-i18next/Trans';
A React component for translating content that contains nested HTML or React elements. Uses interpolation for variables.
initReactI18next
✓ import { initReactI18next } from 'react-i18next';
✗ import initReactI18next from 'react-i18next/initReactI18next';
This plugin must be used with your i18next instance (`i18n.use(initReactI18next)`) to bind it to React.
withTranslation
✓ import { withTranslation } from 'react-i18next';
✗ const withTranslation = require('react-i18next').withTranslation;
A Higher-Order Component (HOC) primarily used for class components or in older React codebases. Not recommended for new functional components.
This quickstart demonstrates how to initialize i18next with react-i18next, use the `useTranslation` hook for simple strings, and the `Trans` component for complex messages with nested React elements and interpolation, including dynamic language switching.
import React from 'react';
import i18n from 'i18next';
import { initReactI18next, useTranslation, Trans } from 'react-i18next';
// 1. Initialize i18next with react-i18next plugin
i18n
.use(initReactI18next) // passes i18n instance to react-i18next
.init({
resources: {
en: {
translation: {
welcome: 'Welcome to our app!',
greeting: 'Hello <0>{{name}}</0>, you have <2>{{count}}</2> unread message.',
nameLabel: 'Your name',
viewMessages: 'View messages'
}
},
fr: {
translation: {
welcome: 'Bienvenue dans notre application !',
greeting: 'Bonjour <0>{{name}}</0>, vous avez <2>{{count}}</2> message(s) non lu(s).',
nameLabel: 'Votre nom',
viewMessages: 'Voir les messages'
}
}
},
lng: 'en', // Default language
fallbackLng: 'en',
interpolation: {
escapeValue: false // React already escapes by default
}
});
// A dummy Link component for the example
const CustomLink = ({ to, children }: { to: string; children: React.ReactNode }) => (
<a href={to}>{children}</a>
);
// 2. Create a functional component using useTranslation and Trans
function App() {
const { t, i18n } = useTranslation();
const userName = 'Alice';
const messageCount = 3;
return (
<div>
<h1>{t('welcome')}</h1>
{/* Example using the Trans component for content with nested elements */}
<Trans i18nKey="greeting" values={{ name: userName, count: messageCount }}>
Hello <strong title={t('nameLabel')}>{{userName}}</strong>, you have <span>{{messageCount}}</span> unread message. <CustomLink to="/messages">{t('viewMessages')}</CustomLink>.
</Trans>
<p>Current language: {i18n.language}</p>
<button onClick={() => i18n.changeLanguage('fr')}>Switch to French</button>
<button onClick={() => i18n.changeLanguage('en')}>Switch to English</button>
</div>
);
}
// Export the App component for rendering in your root ReactDOM.render call
export default App;
Errors
Common errors & fixes
Invariant Violation: Invalid hook call. Hooks can only be called inside of the body of a functional component.
Attempting to use `useTranslation` or other React hooks in a class component, a regular JavaScript function, or with an incompatible React version.
fixEnsure `useTranslation` is called only within a functional React component. Verify your `react` and `react-dom` versions are 16.8.0 or newer. If using a class component, use `withTranslation` HOC instead.
TypeError: i18n.use is not a function
The `i18next` instance is not correctly imported or initialized before attempting to attach `initReactI18next`.
fixEnsure you `import i18n from 'i18next';` and that `i18n` refers to the i18next library instance, not a custom object. The `.use()` method is part of the `i18next` object.
Translation key 'yourKey' does not exist.
The `i18nKey` specified in `t('yourKey')` or `<Trans i18nKey="yourKey"/>` does not exist in the loaded translation resources for the current language.
fixCheck your translation files (e.g., `resources` in `i18n.init()`) to ensure the key exists for the active language. Verify no typos in the key or file path. Ensure translation files are correctly loaded (e.g., via a backend plugin).
Error: `i18next` needs to be initialized first
The `i18next` instance has not been initialized with `i18n.init({...})` before `react-i18next` components or hooks attempt to use it.
fixMake sure `i18n.init({...})` is called and completes before your React application renders, typically in your main `index.js` or `App.js` file. Audit
Dependencies
i18nextrequiredCore internationalization library that react-i18next integrates with.
reactrequiredRequired for React component and hook functionality, especially React 16.8+ for hooks.
typescriptoptionalPeer dependency for type definitions and TypeScript development.