or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

backend.mdconfiguration.mdindex.mdrequest.mdutils.md
tile.json

index.mddocs/

i18next HTTP Backend

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.

Package Information

  • Package Name: i18next-http-backend
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: 
    npm install i18next-http-backend

Core Imports

import HttpBackend from "i18next-http-backend";

For CommonJS:

const HttpBackend = require("i18next-http-backend");

The package supports dual module exports (ESM/CommonJS) with the following structure:

  • ESM: 
    ./esm/index.js
    with type definitions at 
    ./esm/index.d.mts
  • CommonJS: 
    ./cjs/index.js
    with type definitions at 
    ./cjs/index.d.ts
  • Dependencies: Uses 
    cross-fetch
    for polyfilling fetch in Node.js environments

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.

Basic Usage

import i18next from "i18next";
import HttpBackend from "i18next-http-backend";

// Basic setup
i18next
  .use(HttpBackend)
  .init({
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json',
      addPath: '/locales/add/{{lng}}/{{ns}}'
    },
    lng: 'en',
    fallbackLng: 'en',
    ns: ['common'],
    defaultNS: 'common'
  });

// With custom options
i18next
  .use(HttpBackend)
  .init({
    backend: {
      loadPath: 'https://api.example.com/translations/{{lng}}/{{ns}}',
      customHeaders: {
        'Authorization': 'Bearer token'
      },
      requestOptions: {
        mode: 'cors',
        credentials: 'include'
      }
    }
  });

Architecture

i18next-http-backend is built around several key components:

  • Backend Class: Main backend implementation that integrates with i18next's plugin system
  • Request Handler: Adaptive HTTP client that automatically chooses between fetch API and XMLHttpRequest based on environment
  • Configuration System: Comprehensive options system supporting custom headers, request transformers, and path builders
  • Utility Functions: Helper functions for environment detection and promise handling
  • Multi-environment Support: Works seamlessly across Node.js, browsers, and Deno with environment-specific optimizations

Capabilities

Backend Integration

Core backend class that implements the i18next BackendModule interface for loading and saving translation resources via HTTP.

export default class HttpBackend implements BackendModule<HttpBackendOptions> {
  static type: "backend";
  type: "backend";
  services: any;
  options: HttpBackendOptions;
  
  constructor(services?: any, options?: HttpBackendOptions, allOptions?: any);
  init(services?: any, options?: HttpBackendOptions, allOptions?: any): void;
  read(language: string, namespace: string, callback: ReadCallback): void;
  readMulti?(languages: string[], namespaces: string[], callback: MultiReadCallback): void;
  loadUrl(url: string, callback: ReadCallback, languages?: string | string[], namespaces?: string | string[]): void;
  create?(languages: string[], namespace: string, key: string, fallbackValue: string, callback?: (dataArray: any[], resArray: any[]) => void): void;
  reload(): void;
}

type ReadCallback = (error: any, data?: any) => void;
type MultiReadCallback = (error: any, data?: any) => void;

Backend Integration

Configuration Options

Comprehensive configuration system for customizing HTTP requests, paths, parsing, and behavior.

interface HttpBackendOptions {
  loadPath?: LoadPathOption;
  addPath?: AddPathOption;
  parse?(data: string, languages?: string | string[], namespaces?: string | string[]): { [key: string]: any };
  parsePayload?(namespace: string, key: string, fallbackValue?: string): { [key: string]: any };
  parseLoadPayload?(languages: string[], namespaces: string[]): { [key: string]: any } | undefined;
  crossDomain?: boolean;
  withCredentials?: boolean;
  request?(options: HttpBackendOptions, url: string, payload: {} | string, callback: RequestCallback): void;
  queryStringParams?: { [key: string]: string };
  customHeaders?: { [key: string]: string } | (() => { [key: string]: string });
  reloadInterval?: false | number;
  requestOptions?: RequestInit | ((payload: {} | string) => RequestInit);
  alternateFetch?: FetchFunction;
}

type LoadPathOption = string | ((lngs: string[], namespaces: string[]) => string) | ((lngs: string[], namespaces: string[]) => Promise<string>);
type AddPathOption = string | ((lng: string, namespace: string) => string);
type FetchFunction = (input: string, init: RequestInit) => Promise<Response> | void;

Configuration

Request Handling

Adaptive HTTP request system supporting both fetch API and XMLHttpRequest with automatic environment detection.

function request(options: HttpBackendOptions, url: string, payload?: any, callback?: RequestCallback): void;

type RequestCallback = (error: any | undefined | null, response: RequestResponse | undefined | null) => void;

interface RequestResponse {
  status: number;
  data: any;
}

Request Handling

Utility Functions

Helper functions for environment detection, promise handling, and object manipulation.

function defaults(obj: object, ...sources: object[]): object;
function hasXMLHttpRequest(): boolean;
function makePromise(maybePromise: any): Promise<any>;

Utilities