0
# i18next
1
2
i18next is a comprehensive internationalization (i18n) framework for JavaScript applications that works across all environments including browsers, Node.js, and Deno. It provides flexible backend connections, automatic language detection, proper pluralization handling, and an extensive plugin ecosystem for seamless integration with popular frameworks.
3
4
## Package Information
5
6
- **Package Name**: i18next
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install i18next`
10
11
## Core Imports
12
13
```typescript
14
import i18next, { createInstance, t, changeLanguage } from "i18next";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const i18next = require("i18next");
21
const { createInstance, t, changeLanguage } = require("i18next");
22
```
23
24
## Basic Usage
25
26
```typescript
27
import i18next from "i18next";
28
29
// Initialize with basic configuration
30
await i18next.init({
31
lng: "en",
32
fallbackLng: "en",
33
resources: {
34
en: {
35
translation: {
36
"welcome": "Welcome",
37
"hello": "Hello {{name}}!",
38
"item": "{{count}} item",
39
"item_plural": "{{count}} items"
40
}
41
},
42
de: {
43
translation: {
44
"welcome": "Willkommen",
45
"hello": "Hallo {{name}}!",
46
"item": "{{count}} Element",
47
"item_plural": "{{count}} Elemente"
48
}
49
}
50
}
51
});
52
53
// Use translations
54
console.log(i18next.t("welcome")); // "Welcome"
55
console.log(i18next.t("hello", { name: "World" })); // "Hello World!"
56
console.log(i18next.t("item", { count: 5 })); // "5 items"
57
58
// Change language
59
await i18next.changeLanguage("de");
60
console.log(i18next.t("welcome")); // "Willkommen"
61
```
62
63
## Architecture
64
65
i18next is built around several key components:
66
67
- **Core Instance**: Main i18next instance managing configuration, resources, and translation functions
68
- **Resource Store**: Container for all translation resources organized by language and namespace
69
- **Module System**: Plugin architecture supporting backends, language detectors, formatters, and post-processors
70
- **Translation Function**: Primary `t()` function with interpolation, pluralization, and context support
71
- **Services Layer**: Internal services for language utilities, interpolation, formatting, and backend connection
72
- **Event System**: Event-driven architecture enabling reactive updates and plugin communication
73
74
## Capabilities
75
76
### Core Translation
77
78
Primary translation functionality with the `t()` function, supporting interpolation, pluralization, context, and nesting.
79
80
```typescript { .api }
81
function t(key: string | string[], options?: TOptions): string;
82
```
83
84
[Translation Function](./translation.md)
85
86
### Instance Management
87
88
Creating, configuring, and managing i18next instances with initialization options and instance cloning.
89
90
```typescript { .api }
91
function init(options?: InitOptions, callback?: Callback): Promise<TFunction>;
92
function createInstance(options?: InitOptions, callback?: Callback): i18n;
93
function cloneInstance(options?: CloneOptions, callback?: Callback): i18n;
94
```
95
96
[Instance Management](./instance-management.md)
97
98
### Language Management
99
100
Language detection, changing, loading, and handling language hierarchies with fallback support.
101
102
```typescript { .api }
103
function changeLanguage(lng?: string, callback?: Callback): Promise<TFunction>;
104
function loadLanguages(lngs: string | readonly string[], callback?: Callback): Promise<void>;
105
function dir(lng?: string): 'ltr' | 'rtl';
106
```
107
108
[Language Management](./language-management.md)
109
110
### Resource Management
111
112
Loading, storing, and managing translation resources including namespaces, resource bundles, and dynamic resource loading.
113
114
```typescript { .api }
115
function loadResources(callback?: (err: any) => void): void;
116
function addResource(lng: string, ns: string, key: string, value: string, options?: object): i18n;
117
function addResourceBundle(lng: string, ns: string, resources: any, deep?: boolean, overwrite?: boolean): i18n;
118
```
119
120
[Resource Management](./resource-management.md)
121
122
### Plugin System
123
124
Extensible module system supporting backends, language detectors, formatters, post-processors, and third-party integrations.
125
126
```typescript { .api }
127
function use<T extends Module>(module: T | NewableModule<T> | Newable<T>): i18n;
128
129
interface BackendModule<Options = object> extends Module {
130
type: 'backend';
131
init(services: Services, backendOptions: Options, i18nextOptions: InitOptions): void;
132
read(language: string, namespace: string, callback: ReadCallback): void;
133
}
134
```
135
136
[Plugin System](./plugin-system.md)
137
138
## Global Functions
139
140
For convenience, i18next exports several commonly used functions directly:
141
142
```typescript { .api }
143
const createInstance: typeof i18next.createInstance;
144
const init: typeof i18next.init;
145
const t: typeof i18next.t;
146
const changeLanguage: typeof i18next.changeLanguage;
147
const use: typeof i18next.use;
148
const exists: typeof i18next.exists;
149
const getFixedT: typeof i18next.getFixedT;
150
const loadResources: typeof i18next.loadResources;
151
const reloadResources: typeof i18next.reloadResources;
152
const loadNamespaces: typeof i18next.loadNamespaces;
153
const loadLanguages: typeof i18next.loadLanguages;
154
const setDefaultNamespace: typeof i18next.setDefaultNamespace;
155
const hasLoadedNamespace: typeof i18next.hasLoadedNamespace;
156
const dir: typeof i18next.dir;
157
const format: typeof i18next.format;
158
159
// Selector-based key extraction (TypeScript only)
160
function keyFromSelector<S = Record<string, any>, T = string>(
161
selector: ($: S) => T
162
): T;
163
```
164
165
## Core Types
166
167
```typescript { .api }
168
interface i18n {
169
// Core properties
170
language: string;
171
languages: readonly string[];
172
resolvedLanguage?: string;
173
options: InitOptions;
174
modules: Modules;
175
services: Services;
176
store: ResourceStore;
177
178
// Status properties
179
isInitialized: boolean;
180
isInitializing: boolean;
181
initializedStoreOnce: boolean;
182
initializedLanguageOnce: boolean;
183
184
// Main translation function
185
t: TFunction;
186
187
// Format function for interpolation
188
format: FormatFunction;
189
}
190
191
interface InitOptions {
192
lng?: string;
193
fallbackLng?: string | readonly string[] | FallbackLngObjList | ((code: string) => string | readonly string[] | FallbackLngObjList);
194
ns?: string | readonly string[];
195
defaultNS?: string | readonly string[];
196
debug?: boolean;
197
resources?: Resource;
198
preload?: readonly string[];
199
supportedLngs?: readonly string[];
200
nonExplicitSupportedLngs?: boolean;
201
load?: 'all' | 'currentOnly' | 'languageOnly';
202
partialBundledLanguages?: boolean;
203
interpolation?: InterpolationOptions;
204
keySeparator?: string | false;
205
nsSeparator?: string | false;
206
pluralSeparator?: string;
207
contextSeparator?: string;
208
initAsync?: boolean;
209
backend?: any;
210
detection?: any;
211
react?: ReactOptions;
212
[key: string]: any;
213
}
214
215
interface TOptions {
216
defaultValue?: string;
217
lng?: string;
218
lngs?: readonly string[];
219
ns?: string | readonly string[];
220
replace?: { [key: string]: any };
221
count?: number;
222
context?: string;
223
skipInterpolation?: boolean;
224
returnObjects?: boolean;
225
joinArrays?: string;
226
postProcess?: string | string[];
227
keyPrefix?: string;
228
[key: string]: any;
229
}
230
231
type TFunction = (
232
key: string | string[],
233
options?: TOptions
234
) => string;
235
236
type Callback = (error: any, t: TFunction) => void;
237
238
type FormatFunction = (value: any, format: string, lng: string, options: any) => string;
239
240
interface InterpolationOptions {
241
escapeValue?: boolean;
242
prefix?: string;
243
suffix?: string;
244
formatSeparator?: string;
245
unescapePrefix?: string;
246
unescapeSuffix?: string;
247
nestingPrefix?: string;
248
nestingSuffix?: string;
249
maxReplaces?: number;
250
skipOnVariables?: boolean;
251
format?: FormatFunction;
252
}
253
254
interface ReactOptions {
255
wait?: boolean;
256
withRef?: boolean;
257
bindI18n?: string;
258
bindI18nStore?: string;
259
transEmptyNodeValue?: string;
260
transSupportBasicHtmlNodes?: boolean;
261
transKeepBasicHtmlNodesFor?: readonly string[];
262
useSuspense?: boolean;
263
}
264
265
interface Resource {
266
[language: string]: {
267
[namespace: string]: ResourceLanguage;
268
};
269
}
270
271
interface ResourceLanguage {
272
[key: string]: any;
273
}
274
275
interface FallbackLngObjList {
276
[language: string]: readonly string[];
277
}
278
279
interface Services {
280
backendConnector: any;
281
i18nFormat: any;
282
interpolator: Interpolator;
283
languageDetector: any;
284
languageUtils: any;
285
logger: any;
286
pluralResolver: any;
287
resourceStore: ResourceStore;
288
formatter?: Formatter;
289
}
290
291
interface Interpolator {
292
init(options: InterpolationOptions, reset: boolean): undefined;
293
reset(): undefined;
294
resetRegExp(): undefined;
295
interpolate(str: string, data: object, lng: string, options: InterpolationOptions): string;
296
nest(str: string, fc: (...args: any[]) => any, options: InterpolationOptions): string;
297
}
298
299
interface Formatter {
300
init(services: Services, i18nextOptions: InitOptions): void;
301
add(name: string, fc: (value: any, lng: string | undefined, options: any) => string): void;
302
addCached(name: string, fc: (lng: string | undefined, options: any) => (value: any) => string): void;
303
format: FormatFunction;
304
}
305
306
interface ResourceStore {
307
data: Resource;
308
options: InitOptions;
309
on(event: 'added' | 'removed', callback: (lng: string, ns: string) => void): void;
310
off(event: 'added' | 'removed', callback?: (lng: string, ns: string) => void): void;
311
}
312
```