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
```