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)