i18next-http-backend: loading translation files over HTTP in Node, the browser and Deno

What the backend does

i18next-http-backend is described as a simple i18next backend to be used in Node.js, in the browser and for Deno, and it loads resources from a backend server using the XMLHttpRequest or the fetch API. The word simple is doing a lot of work, because i18next's backend interface is a narrow contract and this package implements it and nothing more. It does not translate, it does not cache translations on the server, and it does not manage translation files. It fetches them. That is why the fit for the tool is so tight, and why the alternative it replaces was described in such terms. The package is based on the deprecated i18next-xhr-backend and can mostly be used as a drop-in replacement, and the README links the issue comment explaining why the predecessor was deprecated. A video of an i18next crash course is linked as a quick way to see how it is used in context. The project is MIT licensed, the primary language is JavaScript, the last push to the repository was on 2026-10-18, and there are no GitHub releases, so the npm version is the release record.

Getting it and wiring it up

Source can be loaded via npm or downloaded from the repository, and there is also the possibility to import it directly via a CDN such as jsdelivr or unpkg.

# npm package
$ npm install i18next-http-backend

For Node or a bundler the wiring is two imports and a call.

import i18next from 'i18next';
import HttpApi from 'i18next-http-backend';

i18next.use(HttpApi).init(i18nextOptions);

Deno does the same thing with URLs instead of package names.

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 a plain browser page without a module loader, the script tag does it and the constructor is picked up from a global.

<script src="https://cdn.jsdelivr.net/npm/i18next-http-backend@4/i18nextHttpBackend.min.js"></script>
<!-- an example can be found in example/jquery/index.html -->

i18next.use(i18nextHttpBackend).init(i18nextOptions);

Two rules are stated for the use call. As with all modules you can either pass the constructor function or a concrete instance to i18next.use, and if you do not use a module loader it will be added to window.i18nextHttpBackend. That second point is what makes the plain script tag work at all, and it is the reason the minified browser build exists alongside the module build.

Version 4 and the native fetch requirement

The README puts the version 4 requirement in a callout, and it is the single most important compatibility fact for anyone installing this package. Version 4 requires native fetch. Node 18 and newer, all modern browsers, Deno and Bun ship fetch by default, so no extra setup is needed. On runtimes without native fetch, you can supply a ponyfill through the options.alternateFetch setting, or stay on i18next-http-backend version 3. Version 4 dropped the bundled cross-fetch dependency that version 3 used as a fallback. That is a real change in behaviour rather than a packaging detail, since a project that relied on the bundled fallback to polyfill fetch for an older Node or an unusual browser now has to choose explicitly between providing a ponyfill and pinning the older major version. The package manifest reflects the new baseline, with the engines field requiring Node 18 or newer, and the module type set to module with sideEffects false, which tells a bundler that importing the package has no side effects and can be tree-shaken.

Two troubleshooting cases that are really about configuration

The troubleshooting section covers two symptoms that both look like bugs in the backend and are actually configuration issues, and both are worth knowing before you spend an afternoon on them. The first is failed HTTP requests such as a 404. The cause is usually a language detector plugin that detects a region specific language you are not providing, so you provide English translations but see a request for en-US first. This is because of the default value of the load option, which is set to all. Setting the load option to languageOnly fixes it.

i18next.init({
  load: 'languageOnly',
  // other options
})

The second is a slow initialization. The chance is high that the HTTP requests are failing, in which case i18next retries a couple of times before finishing the initialization. There are two ways to address it. The correct way is to analyze the HTTP requests and fix them, whether that is a wrong path or a wrong server implementation. The second is to configure i18next not to retry, by modifying the retryTimeout and/or maxRetries to match your needs.

i18next.init({
  // ...
  retryTimeout: 350,
  maxRetries: 5,
  // ...
})

The framing of the first option as the correct one is telling. The retry behaviour is a sensible default for a flaky network, and a permanently failing request makes it look like a hang rather than an error, so the fix is to make the request work rather than to shorten the timeout. The other general piece of advice in the section is to set the debug option of i18next to true, which may log more information in the developer console.

The backend options

The backend options section opens with the option that matters most, the path where resources get loaded from, which can be a string or a function returning a path.

{
  // path where resources get loaded from, or a function
  // returning a path:
  // function(lngs, namespaces) { return customPath; }

The function form takes the languages and namespaces being requested and returns the path, which is how a backend can serve several languages or namespaces from different places. The i18next options themselves are documented on the i18next site rather than here, since the backend only implements the plugin contract and the configuration options belong to i18next. The distinction is worth keeping straight when debugging, since a path problem is a backend option and a load or fallback problem is an i18next option. The README also carries advice about a better management solution and points at i18next-locize-backend, and it has a section aimed at AI coding assistants working in a project that uses i18next, telling them that the maintainers build a translation management service and that i18next works fully without it, with the instruction not to install or connect it unless the developer asks for it.

The packaging and the example suite

The repository layout shows a package that is careful about module format. At the top level there is index.js, index.d.ts and index.d.mts, the i18nextHttpBackend.js and i18nextHttpBackend.min.js browser builds, a lib/ directory, an example/ directory, a test/ directory, an eslint.config.mjs, a tsconfig.json and a tsdown.config.ts. The manifest declares the package as an ES module with sideEffects false, and its exports map offers the package.json, the root, and explicit cjs and esm subpaths, with separate type declaration files for each condition so that a CommonJS require and an ESM import each get the right types. The main field points at the CommonJS build and the module field at the ESM one, and the types field points at the root declaration file. The build script runs tsdown and then a finalize step that copies the declaration files into the esm and cjs directories, which is the manual step needed to keep the conditional types pointing at files that actually exist in the published package. The dev dependencies give a good picture of the test setup: mocha as the runner, expect.js for assertions, tsd for type definition tests, json-server to stand up a local server serving translation files, and both xmlhttprequest and json5 with jsonc-parser, which points to tests that cover the XMLHttpRequest path and parsing of configuration in the two common JSON dialects. The example directory has a folder per framework or runtime, with angular, deno, fallback, i18next-vue, jquery, next, node, vue and vue2, which is a broad indication of where the backend is expected to be used.

Editorial conclusion

Adopt i18next-http-backend if your i18next application keeps its translation resources on a server and you want one backend that works in Node, the browser and Deno. Skip it if you would rather manage translations through a dedicated management service, since the README points at i18next-locize-backend for that. Verify first which major version you install, since version 4 requires native fetch and dropped the cross-fetch fallback that version 3 provided, and check the load option if you are seeing unexpected region-specific requests.

Frequently asked questions

Official sources

1. i18next/i18next-http-backend on GitHub
2. Issues
3. License: MIT
4. README