i18next-http-backend

i18next-http-backend is the standard HTTP-loading backend for i18next, the widely used JavaScript internationalization framework. Registered with i18next.use(Backend), it fetches translation JSON from a configurable loadPath template (a static string or a function returning one), interpolates the requested language and namespace into the URL, and hands the parsed result back to i18next’s backend connector — including retry signaling on network failures and 5xx responses.

As of v4 it requires native fetch (Node >=18, modern browsers, Deno, Bun) and no longer bundles a cross-fetch polyfill, though it still supports XMLHttpRequest as a fallback transport and exposes an alternateFetch hook for supplying a ponyfill or intercepting requests (useful for testing or auth-header rewriting). It also supports posting missing translation keys back to a server via addPath, and can transparently reload resources on an interval for long-running server processes.

What You Get

• Drop-in i18next backend — a single i18next.use(Backend).init(...) call with a loadPath template string like /locales/{{lng}}/{{ns}}.json
• Dual transport support — native fetch by default, automatic fallback to XMLHttpRequest in environments without fetch, and an alternateFetch override for ponyfills or test mocking
• Cross-runtime by design — the same package works in Node.js, browsers (including a standalone CDN/UMD build), and Deno with a dedicated import path
• Missing-key reporting — addPath plus saveMissing: true on i18next posts untranslated keys back to a server endpoint for translators to fill in
• Hardened URL interpolation — language and namespace values are validated against a safety allowlist before being substituted into request URLs, blocking path traversal, scheme confusion, and log-injection patterns
• Configurable retry and reload behavior — automatic retry on 5xx/network errors, and an optional interval timer to re-fetch resources in long-lived server processes

Common Use Cases

• Loading translation JSON files from a static /locales/{lng}/{ns}.json path served alongside a web app
• Serving translations from a dedicated backend API, with per-request auth headers via customHeaders
• Server-side rendering setups (Next.js, Node) where a single i18next instance is created once per process, avoiding per-request backend instantiation
• Feeding missing-translation workflows where untranslated keys discovered at runtime are posted to a management endpoint via addPath
• Testing i18next-dependent code by swapping in a mocked alternateFetch implementation instead of monkey-patching global fetch

Under The Hood

Architecture The Backend class in lib/index.js implements i18next’s plugin contract (type = 'backend', read/readMulti/create/reload) and is instantiated by i18next core when passed to .use(). read() funnels into _readAny, which resolves loadPath (a string or a function that may itself return a promise, via makePromise), interpolates the URL template through interpolateUrl in lib/utils.js, and calls loadUrl, which invokes options.request — defaulting to the function exported from lib/request.js — and translates HTTP status codes and thrown errors into retry/no-retry signals fed back to i18next’s backendConnector. reload() implements an optional interval-based refresh using services.backendConnector and languageUtils, unref’d so it never keeps a Node process alive on its own. The whole design centers on one swappable seam — the request(options, url, payload, callback) signature — which is the sanctioned way to fully replace the transport layer.

Tech Stack Zero runtime dependencies; v4 dropped the bundled cross-fetch ponyfill and now requires native fetch (Node >=18). Dev tooling includes ESLint 9 with the neostandard config, Mocha with expect.js for assertions, tsdown to build dual ESM/CJS output driven by the package.json exports map, tsd to type-test the hand-authored .d.ts/.d.mts declarations, and a Node xmlhttprequest polyfill used only to exercise the XHR code path in test. A minified UMD bundle (i18nextHttpBackend.min.js) is checked into the repo root and also distributed via jsDelivr/unpkg for plain-<script> consumption.

Code Quality The test suite (over 600 lines across backendConnector.load.spec.js, http.spec.js, request.spec.js, and security.spec.js) runs the fetch code path and the XHR code path as separate suites, plus a dedicated Deno test directory executed in its own GitHub Actions workflow alongside a Node matrix covering versions 20, 22, and 24. security.spec.js specifically targets the URL-interpolation safety logic — isSafeLangUrlSegment/isSafeNsUrlSegment in lib/utils.js — with inline comments citing a real security advisory for the path-traversal and scheme-confusion issue those guards close. Error handling in request.js explicitly distinguishes network failures, 4xx/5xx responses, and JSON parse errors rather than swallowing them, and TypeScript types are hand-written and validated with tsc --noEmit plus tsd rather than auto-generated.

API Design Getting started is a single .use(Backend) call plus a loadPath string, matching i18next’s plugin convention exactly, so the common case has near-zero boilerplate. Advanced behavior — missing-key posting, multi-language/namespace batching via readMulti, or full request/response interception via a custom request function — layers on top of the same flat options object instead of requiring subclassing. Naming and shape are consistent with the rest of the i18next backend ecosystem (i18next-fs-backend, i18next-chained-backend), which keeps the learning curve low for anyone already using another i18next backend plugin.