0
# React i18next
1
2
React i18next provides comprehensive React integration for the i18next internationalization framework, enabling developers to build multilingual React applications with modern hooks, components, and server-side rendering support. It offers React-specific optimizations like automatic re-rendering when language or translations change, TypeScript support, and compatibility with both modern hooks-based and legacy class-based React components.
3
4
## Package Information
5
6
- **Package Name**: react-i18next
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install react-i18next i18next`
10
11
## Core Imports
12
13
```typescript
14
import { useTranslation, Trans, I18nextProvider, initReactI18next } from "react-i18next";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { useTranslation, Trans, I18nextProvider, initReactI18next } = require("react-i18next");
21
```
22
23
Specialized imports:
24
25
```typescript
26
// Standalone Trans component without context
27
import { Trans } from "react-i18next/TransWithoutContext";
28
29
// i18next plugin initialization
30
import { initReactI18next } from "react-i18next/initReactI18next";
31
32
// ICU message format support (full API)
33
import {
34
Plural,
35
Select,
36
SelectOrdinal,
37
plural,
38
select,
39
selectOrdinal,
40
date,
41
time,
42
number
43
} from "react-i18next/icu.macro";
44
```
45
46
## Basic Usage
47
48
```typescript
49
import i18next from "i18next";
50
import { useTranslation, Trans, I18nextProvider, initReactI18next } from "react-i18next";
51
52
// Initialize i18next with React plugin
53
i18next
54
.use(initReactI18next)
55
.init({
56
lng: "en",
57
fallbackLng: "en",
58
resources: {
59
en: {
60
translation: {
61
welcome: "Welcome to React i18next!",
62
greeting: "Hello, {{name}}!",
63
itemCount: "You have {{count}} item",
64
itemCount_other: "You have {{count}} items"
65
}
66
}
67
}
68
});
69
70
// Hook usage in components
71
function MyComponent() {
72
const { t, i18n, ready } = useTranslation();
73
74
if (!ready) return <div>Loading translations...</div>;
75
76
return (
77
<div>
78
<h1>{t('welcome')}</h1>
79
<p>{t('greeting', { name: 'John' })}</p>
80
<p>{t('itemCount', { count: 5 })}</p>
81
82
{/* Complex translation with HTML using Trans component */}
83
<Trans i18nKey="welcomeMessage" values={{ name: 'John' }}>
84
Welcome back, <strong>{{name}}</strong>! Check your <a href="/inbox">messages</a>.
85
</Trans>
86
87
<button onClick={() => i18n.changeLanguage('de')}>
88
Switch to German
89
</button>
90
<button onClick={() => i18n.changeLanguage('en')}>
91
Switch to English
92
</button>
93
</div>
94
);
95
}
96
97
// App setup with provider
98
function App() {
99
return (
100
<I18nextProvider i18n={i18next}>
101
<MyComponent />
102
</I18nextProvider>
103
);
104
}
105
106
// Advanced usage with multiple namespaces and dynamic loading
107
function AdvancedExample() {
108
const { t, i18n } = useTranslation(['common', 'navigation'], {
109
keyPrefix: 'buttons',
110
useSuspense: false
111
});
112
113
return (
114
<div>
115
<h1>{t('common:title')}</h1>
116
<button>{t('save')}</button> {/* Uses keyPrefix: 'buttons.save' */}
117
<nav>
118
<a href="/">{t('navigation:home')}</a>
119
<a href="/about">{t('navigation:about')}</a>
120
</nav>
121
</div>
122
);
123
}
124
```
125
126
## Architecture
127
128
React i18next is built around several key components:
129
130
- **React Hooks**: `useTranslation` and `useSSR` for modern functional components
131
- **Context System**: `I18nextProvider` and `I18nContext` for dependency injection
132
- **Component Layer**: `Trans` for complex translations with HTML/React interpolation
133
- **HOC Pattern**: `withTranslation` and `withSSR` for class components and legacy support
134
- **Plugin System**: `initReactI18next` plugin integrates with i18next ecosystem
135
- **TypeScript Integration**: Full type safety with generic namespace and key prefix support
136
- **SSR Support**: Server-side rendering utilities for Next.js and other frameworks
137
138
## Capabilities
139
140
### React Hooks
141
142
Modern React hooks providing translation functions and i18next instance access with automatic re-rendering on language changes.
143
144
```typescript { .api }
145
function useTranslation<Ns, KPrefix>(
146
ns?: Ns,
147
options?: UseTranslationOptions<KPrefix>
148
): UseTranslationResponse<Ns, KPrefix>;
149
150
interface UseTranslationOptions<KPrefix> {
151
i18n?: i18n;
152
useSuspense?: boolean;
153
keyPrefix?: KPrefix;
154
bindI18n?: string | false;
155
nsMode?: 'fallback' | 'default';
156
lng?: string;
157
}
158
159
type UseTranslationResponse<Ns, KPrefix> = [
160
t: TFunction<Ns, KPrefix>,
161
i18n: i18n,
162
ready: boolean
163
] & {
164
t: TFunction<Ns, KPrefix>;
165
i18n: i18n;
166
ready: boolean;
167
};
168
```
169
170
[React Hooks](./hooks.md)
171
172
### React Components
173
174
Components for rendering translations with HTML interpolation, provider context, and render prop patterns.
175
176
```typescript { .api }
177
function Trans<Key, Ns, KPrefix, TContext, TOpt, E>(
178
props: TransProps<Key, Ns, KPrefix, TContext, TOpt, E>
179
): React.ReactElement;
180
181
function I18nextProvider(props: I18nextProviderProps): React.FunctionComponent;
182
183
function Translation<Ns, KPrefix>(
184
props: TranslationProps<Ns, KPrefix>
185
): React.ReactNode;
186
187
interface I18nextProviderProps {
188
children?: React.ReactNode;
189
i18n: i18n;
190
defaultNS?: string | string[];
191
}
192
```
193
194
[React Components](./components.md)
195
196
### Higher-Order Components
197
198
HOCs for injecting translation functionality into class components and legacy React patterns.
199
200
```typescript { .api }
201
function withTranslation<Ns, KPrefix>(
202
ns?: Ns,
203
options?: { withRef?: boolean; keyPrefix?: KPrefix }
204
): <C extends React.ComponentType<any>>(component: C) => React.ComponentType<any>;
205
206
function withSSR(): <Props>(
207
WrappedComponent: React.ComponentType<Props>
208
) => React.ComponentType<Props & { initialI18nStore: Resource; initialLanguage: string }>;
209
```
210
211
[Higher-Order Components](./hocs.md)
212
213
### Server-Side Rendering
214
215
Utilities for server-side rendering support including initial data hydration and SSR-safe component rendering.
216
217
```typescript { .api }
218
function useSSR(initialI18nStore: Resource, initialLanguage: string): void;
219
220
function composeInitialProps(ForComponent: any): (ctx: unknown) => Promise<any>;
221
222
function getInitialProps(): {
223
initialI18nStore: { [ns: string]: {} };
224
initialLanguage: string;
225
};
226
```
227
228
[Server-Side Rendering](./ssr.md)
229
230
### ICU Message Format Support
231
232
Babel macro providing compile-time ICU message format transformation with React component and template literal support.
233
234
```typescript { .api }
235
// Template literal functions (compile-time)
236
function plural(strings: TemplateStringsArray, variable: number, ...args: ValidInterpolations[]): string;
237
function select(strings: TemplateStringsArray, variable: string, ...args: ValidInterpolations[]): string;
238
function date(strings: TemplateStringsArray, variable: Date): string;
239
240
// React components
241
function Plural<T, Key, Ns>(props: PluralProps<T, Key, Ns>): ReactElement;
242
function Select<Key, Ns>(props: SelectProps<Key, Ns>): ReactElement;
243
```
244
245
[ICU Message Format](./icu-macro.md)
246
247
### Standalone Components
248
249
Direct component imports without context dependency for advanced use cases and custom i18next configurations.
250
251
```typescript { .api }
252
// TransWithoutContext - standalone Trans component
253
const TransWithoutContext: typeof Trans;
254
```
255
256
## Core Types
257
258
```typescript { .api }
259
// Core configuration and utilities
260
interface ReactOptions {
261
bindI18n?: string | false;
262
bindI18nStore?: string;
263
transEmptyNodeValue?: string;
264
transSupportBasicHtmlNodes?: boolean;
265
transWrapTextNodes?: string;
266
transKeepBasicHtmlNodesFor?: string[];
267
useSuspense?: boolean;
268
unescape?: (str: string) => string;
269
}
270
271
// Context and reporting
272
interface ReportNamespaces {
273
addUsedNamespaces(namespaces: Namespace): void;
274
getUsedNamespaces(): string[];
275
}
276
277
// Helper types for type system integration
278
type $Tuple<T> = readonly [T?, ...T[]];
279
type $Subtract<T extends K, K> = Omit<T, keyof K>;
280
281
// Error handling
282
type ErrorCode =
283
| 'NO_I18NEXT_INSTANCE'
284
| 'NO_LANGUAGES'
285
| 'DEPRECATED_OPTION'
286
| 'TRANS_NULL_VALUE'
287
| 'TRANS_INVALID_OBJ'
288
| 'TRANS_INVALID_VAR'
289
| 'TRANS_INVALID_COMPONENTS';
290
291
type ErrorArgs = readonly [string, ErrorMeta | undefined, ...any[]];
292
```
293
294
## Configuration Functions
295
296
```typescript { .api }
297
// Global defaults management
298
function setDefaults(options: ReactOptions): void;
299
function getDefaults(): ReactOptions;
300
301
// Global i18next instance management
302
function setI18n(instance: i18n): void;
303
function getI18n(): i18n;
304
305
// Plugin initialization
306
const initReactI18next: ThirdPartyModule;
307
```