Registry / http-networking / i18next-http-backend

i18next-http-backend

JSON →
library3.0.5jsnpmunverified

i18next-http-backend is a backend layer for the i18next internationalization framework, designed to load translation resources from a remote server using standard HTTP requests (XMLHttpRequest or Fetch API). It supports diverse JavaScript environments, functioning seamlessly in Node.js, modern browsers, and Deno. Currently at stable version 3.0.5, it receives updates as needed to maintain compatibility and introduce improvements. It's explicitly designed as a modern, drop-in replacement for the deprecated i18next-xhr-backend, addressing its limitations. Its primary differentiation is its broad platform support and direct integration with i18next's resource loading mechanism, enabling developers to manage translations externally without bundling them into the client-side application. It offers configurable options for request handling, retry logic, and resource path resolution.

npm install i18next-http-backend
INSTALL
IMPORT
SIG · I18NEXT-HTTP-BACKE
I
i18next-http-backend
http-networkingjavascriptv3.0.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HttpBackend
import HttpBackend from 'i18next-http-backend';
import { HttpBackend } from 'i18next-http-backend';
The HttpBackend class is exported as the default export of the package.
HttpBackend (CommonJS)
const HttpBackend = require('i18next-http-backend');
const HttpBackend = require('i18next-http-backend').default;
In CommonJS, the default export is directly assigned when requiring the module.
HttpBackendOptions (Type)
import type { HttpBackendOptions } from 'i18next-http-backend';
TypeScript users can import this interface for configuring the HttpBackend.

This quickstart demonstrates how to initialize i18next with the HttpBackend, configuring it to load translation files from a specified path. It shows how to set up namespaces, fallback languages, and perform basic translation lookups, including changing the active language, using a mock fetch for a runnable example.

import i18next from 'i18next'; import HttpBackend from 'i18next-http-backend'; // In a real application, translation files would be served from a web server. // This example uses a mock fetch to simulate loading. const mockTranslations = { en: { translation: { "welcome": "Welcome to our app!", "greeting": "Hello, {{name}}!" } }, es: { translation: { "welcome": "¡Bienvenido a nuestra aplicación!", "greeting": "¡Hola, {{name}}!" } } }; // Simulate a fetch function that would load resources from a URL const mockFetch = async (url: string) => { console.log(`Simulating fetch for: ${url}`); const parts = url.split('/'); const lang = parts[parts.length - 2]; // e.g., 'en' from '/locales/en/translation.json' const ns = parts[parts.length - 1].split('.')[0]; // e.g., 'translation' if (mockTranslations[lang as keyof typeof mockTranslations] && mockTranslations[lang as keyof typeof mockTranslations][ns as keyof typeof mockTranslations[keyof typeof mockTranslations]]) { return { ok: true, status: 200, json: () => Promise.resolve(mockTranslations[lang as keyof typeof mockTranslations][ns as keyof typeof mockTranslations[keyof typeof mockTranslations]]) }; } return { ok: false, status: 404, json: () => Promise.resolve({}) // Return empty object for 404 }; }; i18next .use(HttpBackend) .init({ lng: 'en', fallbackLng: 'en', debug: true, // Enable debug for more console output backend: { loadPath: '/locales/{{lng}}/{{ns}}.json', // Provide a custom request function to use the mock fetch request: (options, url, payload, callback) => { mockFetch(url) .then(response => { if (response.ok) { response.json().then(data => callback(null, { status: response.status, data })); } else { callback(new Error(`Failed to load ${url}: ${response.status}`), { status: response.status }); } }) .catch(error => callback(error, { status: 0 })); } }, ns: ['translation'], // Default namespace defaultNS: 'translation', interpolation: { escapeValue: false, // React already escapes by default }, }) .then(() => { console.log(i18next.t('welcome')); console.log(i18next.t('greeting', { name: 'World' })); console.log(i18next.t('missingKey')); // This will show as 'missingKey' due to no translation // Change language and translate again i18next.changeLanguage('es').then(() => { console.log(i18next.t('welcome')); }); }) .catch((err) => console.error("i18next initialization error:", err));
Debug
Known issues
breakingi18next-http-backend is a direct replacement for the deprecated i18next-xhr-backend. While largely a drop-in replacement, be aware of subtle differences in how HTTP requests are handled (Fetch API vs. XMLHttpRequest) which might affect custom configurations or older browser compatibility if not properly polyfilled.
fix
Replace `i18next-xhr-backend` with `i18next-http-backend`. Review any custom `loadPath` or `request` options, especially if they implicitly relied on XHR-specific behaviors or relied on older browser XMLHttpRequest APIs directly. Ensure proper polyfills are in place for Fetch API if targeting very old browsers.
affects: >=1.0.0
gotchaEncountering 404 errors for region-specific languages (e.g., requesting 'en-US' when only 'en' translations are provided) is a common issue. This often happens if an i18next language detector is active and the `load` option is set to its default 'all'.
fix
Set `i18next.init({ load: 'languageOnly' })` to instruct i18next to only load the base language (e.g., 'en') and ignore region specifics ('-US'). Alternatively, ensure you provide translations for all detected regional variants or configure the language detector to be less specific.
affects: >=1.0.0
gotchaSlow i18next initialization can occur if HTTP requests for translation files fail. i18next is configured to retry these requests multiple times by default, leading to delays before it completes initialization.
fix
First, debug and resolve the underlying HTTP request issues (e.g., incorrect `backend.loadPath`, misconfigured server, CORS issues). If transient failures are expected, you can configure `i18next.init({ retryTimeout: 350, maxRetries: 1 })` to reduce the number of retry attempts and speed up the fallback process.
affects: >=1.0.0
gotchaVersion 3.0.0 introduced breaking changes for ESM build environments that do not support top-level await, and addressed security vulnerabilities.
fix
For ESM environments without top-level await support, import the CommonJS (CJS) export: `import HttpBackend from 'i18next-http-backend/cjs';`. Ensure you are on the latest patch release (e.g., 3.0.5) to benefit from security fixes related to URL construction and log forging.
affects: >=3.0.0
Errors
Common errors & fixes
Seeing failed http requests, like 404?
A language detector requests a region-specific language (e.g., 'en-US') for which no translation is provided, the 'loadPath' is incorrect, or the backend server is not serving the files.
fix
Set `i18next.init({ load: 'languageOnly' })` to prevent requests for region-specific languages. Verify `backend.loadPath` is correct and that your server is configured to serve the translation files at that path with appropriate CORS headers.
Slow i18next initialization?
HTTP requests for translation files are failing, causing i18next to retry multiple times before giving up, leading to delays.
fix
Analyze HTTP requests and fix the root cause (e.g., incorrect `loadPath`, server misconfiguration). Alternatively, configure `i18next.init({ retryTimeout: 350, maxRetries: 1 })` to reduce retry attempts and hasten initialization when requests are failing.
Upgrade
Version history
3.0.5latest on npm
Audit
Dependencies
i18nextrequiredCore internationalization framework this backend integrates with.
Agent activity
2 hits · last 30 days
node
2
Resources
i18next-http-backend — npm install i18next-http-backend · libregistry