# i18next-http-backend
> i18next-http-backend is a backend layer for i18next using in Node.js, in the browser and for Deno.
Latest version **4.0.2** (published 2026-09-02) · MIT license · 0 weekly downloads
## Install
```sh
npm install i18next-http-backend
pnpm add i18next-http-backend
yarn add i18next-http-backend
bun add i18next-http-backend
```
## Health
**Score 70/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 4.0.2 |
| Published | 2026-09-02 |
| First published | 2020-04-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 102.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 525 |
| Maintainers | adrai, jamuhl |
| Keywords | i18next, i18next-backend, i18next-http-backend |
## Links
- npm: https://www.npmjs.com/package/i18next-http-backend
- Repository: https://github.com/i18next/i18next-http-backend
- Issues: https://github.com/i18next/i18next-http-backend/issues
- npm.io page: https://npm.io/package/i18next-http-backend
## Alternatives
- [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads
- [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads
- [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads
- [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads
- [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads
## Recent versions
- 4.0.2 (latest) — 2026-09-02
- 4.0.1 — 2026-07-28
- 4.0.0 — 2026-05-04
- 3.0.6 — 2026-04-23
- 3.0.5 — 2026-04-18
- 3.0.4 — 2026-03-31
- 2.7.3 — 2025-01-23
- 2.7.2 — 2025-01-23
- 3.0.2 — 2025-01-23
- 3.0.1 — 2024-11-21
- 2.7.1 — 2024-11-21
- 3.0.0 — 2024-11-21
- 2.7.0 — 2024-11-20
- 2.6.2 — 2024-10-03
- 2.6.1 — 2024-08-21
- … 64 more at https://npm.io/package/i18next-http-backend/versions
## README
# Introduction
[](https://github.com/i18next/i18next-http-backend/actions?query=workflow%3Anode)
[](https://github.com/i18next/i18next-http-backend/actions?query=workflow%3Adeno)
[](https://www.npmjs.com/package/i18next-http-backend)
This is a simple i18next backend to be used in Node.js, in the browser and for Deno. It will load resources from a backend server using the XMLHttpRequest or the fetch API.
Get a first idea on how it is used in [this i18next crash course video](https://youtu.be/SA_9i4TtxLQ?t=953).
It's based on the deprecated [i18next-xhr-backend](https://github.com/i18next/i18next-xhr-backend) and can mostly be used as a drop-in replacement.
*[Why i18next-xhr-backend was deprecated?](https://github.com/i18next/i18next-xhr-backend/issues/348#issuecomment-663060275)*
## Advice:
If you don't like to manage your translation files manually or are simply looking for a [better management solution](https://www.locize.com?utm_source=i18next_http_backend_readme&utm_medium=github&utm_campaign=readme), take a look at [i18next-locize-backend](https://github.com/locize/i18next-locize-backend). The i18next [backend plugin](https://www.i18next.com/overview/plugins-and-utils#backends) for 🌐 [Locize](https://www.locize.com?utm_source=i18next_http_backend_readme&utm_medium=github&utm_campaign=readme) ☁️.
Starting from an app with hardcoded strings? Run `npx i18next-cli localize` — one command that wraps strings in `t()`, extracts keys, connects to [Locize](https://www.locize.com?from=i18next-http-backend_readme__localize) and AI-translates your app. See the [launch post](https://www.locize.com/blog/i18next-cli-localize?from=i18next-http-backend_readme__localize).
*To see [i18next-locize-backend](https://github.com/locize/i18next-locize-backend) in a working app example, check out:*
- *[this react-tutorial](https://github.com/locize/react-tutorial) starting from [Step 2](https://github.com/locize/react-tutorial#step-2---use-the-locize-cdn)*
- *[this guide](https://www.locize.com/blog/react-i18next/?utm_source=i18next_http_backend_readme&utm_medium=github&utm_campaign=readme) starting from the step of [replacing i18next-http-backend with i18next-locize-backend](https://www.locize.com/blog/react-i18next/?utm_source=i18next_http_backend_readme&utm_medium=github&utm_campaign=readme#how-look)*
- *[this Angular blog post](https://www.locize.com/blog/angular-i18next/?utm_source=i18next_http_backend_readme&utm_medium=github&utm_campaign=readme) [introducing i18next-locize-backend](https://www.locize.com/blog/angular-i18next/?utm_source=i18next_http_backend_readme&utm_medium=github&utm_campaign=readme#how-look)*
- *[the code integration part](https://www.youtube.com/watch?v=TFV_vhJs5DY&t=294s) in this [YouTube video](https://www.youtube.com/watch?v=TFV_vhJs5DY)*
## Troubleshooting
Make sure you set the `debug` option of i18next to `true`. This will maybe log more information in the developer console.
### Seeing failed http requests, like 404?
Are you using a [language detector](https://github.com/i18next/i18next-browser-languageDetector) plugin that detects region specific languages you are not providing? i.e. you provide `'en'` translations but you see a `'en-US'` request first?
This is because of the default `load` [option](https://www.i18next.com/overview/configuration-options) set to `'all'`.
Try to set the `load` [option](https://www.i18next.com/overview/configuration-options) to `'languageOnly'`
```javascript
i18next.init({
load: 'languageOnly',
// other options
})
```
[This article](https://www.locize.com/blog/i18next-translations-not-loaded?utm_source=i18next_http_backend_readme&utm_medium=github&utm_campaign=readme) may also help to understand/investigate that.
### Slow i18next initialization?
The chance is high, that your http requests fails. In that case i18next retries a couple of times before finishing the initialization.
You have 2 options to address this:
*1) The correct way:*
Analyze your http requests and fix them. (Wrong path? Wrong server implementation? etc...)
*2) Configure i18next to not retry:*
Modify the `retryTimeout` and/or `maxRetries` to match your needs. (i.e. set `maxRetries: 1`)
```js
i18next.init({
// ...
retryTimeout: 350,
maxRetries: 5,
// ...
})
```
# Getting started
Source can be loaded via [npm](https://www.npmjs.com/package/i18next-http-backend) or [downloaded](https://github.com/i18next/i18next-http-backend/blob/master/i18nextHttpBackend.min.js) from this repo.
There's also the possibility to directly import it via a CDN like [jsdelivr](https://cdn.jsdelivr.net/npm/i18next-http-backend@4/i18nextHttpBackend.min.js) or [unpkg](https://unpkg.com/i18next-http-backend@4/i18nextHttpBackend.min.js) or similar.
```bash
# npm package
$ npm install i18next-http-backend
```
> **v4 requires native `fetch`.** Node ≥ 18, all modern browsers, Deno, and Bun ship `fetch` by default — no extra setup needed. On runtimes without native `fetch`, supply a ponyfill via `options.alternateFetch` (see below) or stay on `i18next-http-backend@3`. v4 dropped the bundled `cross-fetch` dependency that v3 used as a fallback.
Wiring up:
```js
import i18next from 'i18next';
import HttpApi from 'i18next-http-backend';
i18next.use(HttpApi).init(i18nextOptions);
```
for Deno:
```js
import i18next from 'https://deno.land/x/i18next/index.js'
import Backend from 'https://deno.land/x/i18next_http_backend/index.js'
i18next.use(Backend).init(i18nextOptions);
```
for plain browser:
```html
```
```js
i18next.use(i18nextHttpBackend).init(i18nextOptions);
```
- As with all modules you can either pass the constructor function (class) to the i18next.use or a concrete instance.
- If you don't use a module loader it will be added to `window.i18nextHttpBackend`
## Backend Options
```js
{
// path where resources get loaded from, or a function
// returning a path:
// function(lngs, namespaces) { return customPath; }
// the returned path will interpolate lng, ns if provided like giving a static path
// the function might return a promise
// returning falsy will abort the download
//
// If not used with i18next-multiload-backend-adapter, lngs and namespaces will have only one element each,
// If used with i18next-multiload-backend-adapter, lngs and namespaces can have multiple elements
// and also your server needs to support multiloading
// /locales/resources.json?lng=de+en&ns=ns1+ns2
// Adapter is needed to enable MultiLoading https://github.com/i18next/i18next-multiload-backend-adapter
// Returned JSON structure in this case is
// {
// lang : {
// namespaceA: {},
// namespaceB: {},
// ...etc
// }
// }
loadPath: '/locales/{{lng}}/{{ns}}.json',
// path to post missing resources, or a function
// function(lng, namespace) { return customPath; }
// the returned path will interpolate lng, ns if provided like giving a static path
//
// note that this only works when initialized with { saveMissing: true }
// (see https://www.i18next.com/overview/configuration-options)
addPath: '/locales/add/{{lng}}/{{ns}}',
// parse data after it has been fetched
// in example use https://www.npmjs.com/package/json5 or https://www.npmjs.com/package/jsonc-parser
// here it removes the letter a from the json (bad idea)
parse: function(data) { return data.replace(/a/g, ''); },
// parse data before it has been sent by addPath
parsePayload: function(namespace, key, fallbackValue) { return { key: fallbackValue || "" } },
// parse data before it has been sent by loadPath
// if value returned it will send a POST request
parseLoadPayload: function(languages, namespaces) { return undefined },
// allow cross domain requests => used for XmlHttpRequest
crossDomain: false,
// allow credentials on cross domain requests => used for XmlHttpRequest
withCredentials: false,
// overrideMimeType sets request.overrideMimeType("application/json") => used for XmlHttpRequest
overrideMimeType: false,
// custom request headers sets request.setRequestHeader(key, value)
customHeaders: {
authorization: 'foo',
// ...
},
// can also be a function, that returns the headers
customHeaders: () => ({
authorization: 'foo',
// ...
}),
requestOptions: { // used for fetch, can also be a function (payload) => ({ method: 'GET' })
mode: 'cors',
credentials: 'same-origin',
cache: 'default'
},
// define a custom request function — replaces the built-in fetch/XHR call entirely.
// For lighter-weight overrides (e.g. test-time mocking, or supplying a fetch
// ponyfill on legacy runtimes), prefer `alternateFetch` (see below).
//
// 'options' will be this entire options object
// 'url' will be passed the value of 'loadPath'
// 'payload' will be a key:value object used when saving missing translations
// 'callback' is a function that takes two parameters, 'err' and 'res'.
// 'err' should be an error
// 'res' should be an object with a 'status' property and a 'data' property containing a stringified object instance beeing the key:value translation pairs for the
// requested language and namespace, or null in case of an error.
request: function (options, url, payload, callback) {},
// optional: provide an alternative fetch implementation (must match the
// standard `fetch(input, init)` signature). Useful for:
// - test mocking (return a stubbed Response without monkey-patching globals)
// - injecting a fetch ponyfill on runtimes without native fetch
// - intercepting requests for tracing / auth header rewriting
// Returning anything other than a Promise causes the backend to fall through
// to the built-in fetch (or XHR) call — useful for selective interception.
// Not used if a custom `request` function is supplied, or when the backend
// selects XHR over fetch.
alternateFetch: undefined, // (url, init) => Promise,
// adds parameters to resource URL. 'example.com' -> 'example.com?v=1.3.5'
queryStringParams: { v: '1.3.5' },
// can be used to reload resources in a specific interval (milliseconds) (useful in server environments)
// default: false in the browser, 60 * 60 * 1000 (1 hour) everywhere else
reloadInterval: false
}
```
> **Server side:** the reload timer keeps the i18next instance alive for as long as the process runs. That is what you want for one long-lived instance, and a trap for anything short-lived: if you create a **new i18next instance per request or per render** (server-side rendering counts, a component that initializes i18next runs on the server too), each one leaves a live timer behind and keeps refetching forever. Nothing errors and the process still exits normally, because the timer is `unref`ed. Create the instance once per process and reuse it, or set `reloadInterval: false` on instances that are not that singleton.
Options can be passed in:
**preferred** - by setting options.backend in i18next.init:
```js
import i18next from 'i18next';
import HttpApi from 'i18next-http-backend';
i18next.use(HttpApi).init({
backend: options,
});
```
on construction:
```js
import HttpApi from 'i18next-http-backend';
const HttpApi = new HttpApi(null, options);
```
via calling init:
```js
import HttpApi from 'i18next-http-backend';
const HttpApi = new HttpApi();
HttpApi.init(null, options);
```
## TypeScript
To properly type the backend options, you can import the `HttpBackendOptions` interface and use it as a generic type parameter to the i18next's `init` method, e.g.:
```ts
import i18n from 'i18next'
import HttpBackend, { HttpBackendOptions } from 'i18next-http-backend'
i18n
.use(HttpBackend)
.init({
backend: {
// http backend options
},
// other i18next options
})
```
---
Gold Sponsors
---
**From the creators of i18next: localization as a service - locize.com**
A translation management system built around the i18next ecosystem - [locize.com](https://www.locize.com?utm_source=i18next_http_backend_readme&utm_medium=github&utm_campaign=readme).
With using [locize](https://www.locize.com/?utm_source=i18next_http_backend_readme&utm_medium=github&utm_campaign=readme) you directly support the future of i18next.
---
---
_Source: https://npm.io/package/i18next-http-backend · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._