0
# i18next HTTP Backend
1
2
i18next-http-backend is a backend layer for the i18next internationalization framework that loads translation resources from HTTP endpoints. It provides a modern replacement for the deprecated i18next-xhr-backend, supporting Node.js, browser, and Deno environments with both XMLHttpRequest and fetch API implementations.
3
4
## Package Information
5
6
- **Package Name**: i18next-http-backend
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install i18next-http-backend`
10
11
## Core Imports
12
13
```typescript
14
import HttpBackend from "i18next-http-backend";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const HttpBackend = require("i18next-http-backend");
21
```
22
23
The package supports dual module exports (ESM/CommonJS) with the following structure:
24
- **ESM**: `./esm/index.js` with type definitions at `./esm/index.d.mts`
25
- **CommonJS**: `./cjs/index.js` with type definitions at `./cjs/index.d.ts`
26
- **Dependencies**: Uses `cross-fetch` for polyfilling fetch in Node.js environments
27
28
Note: Utility functions are internal implementation details and not exposed through the main package exports. They should be accessed through the Backend class methods rather than directly imported.
29
30
## Basic Usage
31
32
```typescript
33
import i18next from "i18next";
34
import HttpBackend from "i18next-http-backend";
35
36
// Basic setup
37
i18next
38
.use(HttpBackend)
39
.init({
40
backend: {
41
loadPath: '/locales/{{lng}}/{{ns}}.json',
42
addPath: '/locales/add/{{lng}}/{{ns}}'
43
},
44
lng: 'en',
45
fallbackLng: 'en',
46
ns: ['common'],
47
defaultNS: 'common'
48
});
49
50
// With custom options
51
i18next
52
.use(HttpBackend)
53
.init({
54
backend: {
55
loadPath: 'https://api.example.com/translations/{{lng}}/{{ns}}',
56
customHeaders: {
57
'Authorization': 'Bearer token'
58
},
59
requestOptions: {
60
mode: 'cors',
61
credentials: 'include'
62
}
63
}
64
});
65
```
66
67
## Architecture
68
69
i18next-http-backend is built around several key components:
70
71
- **Backend Class**: Main backend implementation that integrates with i18next's plugin system
72
- **Request Handler**: Adaptive HTTP client that automatically chooses between fetch API and XMLHttpRequest based on environment
73
- **Configuration System**: Comprehensive options system supporting custom headers, request transformers, and path builders
74
- **Utility Functions**: Helper functions for environment detection and promise handling
75
- **Multi-environment Support**: Works seamlessly across Node.js, browsers, and Deno with environment-specific optimizations
76
77
## Capabilities
78
79
### Backend Integration
80
81
Core backend class that implements the i18next BackendModule interface for loading and saving translation resources via HTTP.
82
83
```typescript { .api }
84
export default class HttpBackend implements BackendModule<HttpBackendOptions> {
85
static type: "backend";
86
type: "backend";
87
services: any;
88
options: HttpBackendOptions;
89
90
constructor(services?: any, options?: HttpBackendOptions, allOptions?: any);
91
init(services?: any, options?: HttpBackendOptions, allOptions?: any): void;
92
read(language: string, namespace: string, callback: ReadCallback): void;
93
readMulti?(languages: string[], namespaces: string[], callback: MultiReadCallback): void;
94
loadUrl(url: string, callback: ReadCallback, languages?: string | string[], namespaces?: string | string[]): void;
95
create?(languages: string[], namespace: string, key: string, fallbackValue: string, callback?: (dataArray: any[], resArray: any[]) => void): void;
96
reload(): void;
97
}
98
99
type ReadCallback = (error: any, data?: any) => void;
100
type MultiReadCallback = (error: any, data?: any) => void;
101
```
102
103
[Backend Integration](./backend.md)
104
105
### Configuration Options
106
107
Comprehensive configuration system for customizing HTTP requests, paths, parsing, and behavior.
108
109
```typescript { .api }
110
interface HttpBackendOptions {
111
loadPath?: LoadPathOption;
112
addPath?: AddPathOption;
113
parse?(data: string, languages?: string | string[], namespaces?: string | string[]): { [key: string]: any };
114
parsePayload?(namespace: string, key: string, fallbackValue?: string): { [key: string]: any };
115
parseLoadPayload?(languages: string[], namespaces: string[]): { [key: string]: any } | undefined;
116
crossDomain?: boolean;
117
withCredentials?: boolean;
118
request?(options: HttpBackendOptions, url: string, payload: {} | string, callback: RequestCallback): void;
119
queryStringParams?: { [key: string]: string };
120
customHeaders?: { [key: string]: string } | (() => { [key: string]: string });
121
reloadInterval?: false | number;
122
requestOptions?: RequestInit | ((payload: {} | string) => RequestInit);
123
alternateFetch?: FetchFunction;
124
}
125
126
type LoadPathOption = string | ((lngs: string[], namespaces: string[]) => string) | ((lngs: string[], namespaces: string[]) => Promise<string>);
127
type AddPathOption = string | ((lng: string, namespace: string) => string);
128
type FetchFunction = (input: string, init: RequestInit) => Promise<Response> | void;
129
```
130
131
[Configuration](./configuration.md)
132
133
### Request Handling
134
135
Adaptive HTTP request system supporting both fetch API and XMLHttpRequest with automatic environment detection.
136
137
```typescript { .api }
138
function request(options: HttpBackendOptions, url: string, payload?: any, callback?: RequestCallback): void;
139
140
type RequestCallback = (error: any | undefined | null, response: RequestResponse | undefined | null) => void;
141
142
interface RequestResponse {
143
status: number;
144
data: any;
145
}
146
```
147
148
[Request Handling](./request.md)
149
150
### Utility Functions
151
152
Helper functions for environment detection, promise handling, and object manipulation.
153
154
```typescript { .api }
155
function defaults(obj: object, ...sources: object[]): object;
156
function hasXMLHttpRequest(): boolean;
157
function makePromise(maybePromise: any): Promise<any>;
158
```
159
160
[Utilities](./utils.md)