or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdinstance-management.mdlanguage-management.mdplugin-system.mdresource-management.mdtranslation.md
tile.json

index.mddocs/

i18next

i18next is a comprehensive internationalization (i18n) framework for JavaScript applications that works across all environments including browsers, Node.js, and Deno. It provides flexible backend connections, automatic language detection, proper pluralization handling, and an extensive plugin ecosystem for seamless integration with popular frameworks.

Package Information

  • Package Name: i18next
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: 
    npm install i18next

Core Imports

import i18next, { createInstance, t, changeLanguage } from "i18next";

For CommonJS:

const i18next = require("i18next");
const { createInstance, t, changeLanguage } = require("i18next");

Basic Usage

import i18next from "i18next";

// Initialize with basic configuration
await i18next.init({
  lng: "en",
  fallbackLng: "en",
  resources: {
    en: {
      translation: {
        "welcome": "Welcome",
        "hello": "Hello {{name}}!",
        "item": "{{count}} item",
        "item_plural": "{{count}} items"
      }
    },
    de: {
      translation: {
        "welcome": "Willkommen",
        "hello": "Hallo {{name}}!",
        "item": "{{count}} Element",
        "item_plural": "{{count}} Elemente"
      }
    }
  }
});

// Use translations
console.log(i18next.t("welcome")); // "Welcome"
console.log(i18next.t("hello", { name: "World" })); // "Hello World!"
console.log(i18next.t("item", { count: 5 })); // "5 items"

// Change language
await i18next.changeLanguage("de");
console.log(i18next.t("welcome")); // "Willkommen"

Architecture

i18next is built around several key components:

  • Core Instance: Main i18next instance managing configuration, resources, and translation functions
  • Resource Store: Container for all translation resources organized by language and namespace
  • Module System: Plugin architecture supporting backends, language detectors, formatters, and post-processors
  • Translation Function: Primary 
    t()
    function with interpolation, pluralization, and context support
  • Services Layer: Internal services for language utilities, interpolation, formatting, and backend connection
  • Event System: Event-driven architecture enabling reactive updates and plugin communication

Capabilities

Core Translation

Primary translation functionality with the 

t()
function, supporting interpolation, pluralization, context, and nesting.

function t(key: string | string[], options?: TOptions): string;

Translation Function

Instance Management

Creating, configuring, and managing i18next instances with initialization options and instance cloning.

function init(options?: InitOptions, callback?: Callback): Promise<TFunction>;
function createInstance(options?: InitOptions, callback?: Callback): i18n;
function cloneInstance(options?: CloneOptions, callback?: Callback): i18n;

Instance Management

Language Management

Language detection, changing, loading, and handling language hierarchies with fallback support.

function changeLanguage(lng?: string, callback?: Callback): Promise<TFunction>;
function loadLanguages(lngs: string | readonly string[], callback?: Callback): Promise<void>;
function dir(lng?: string): 'ltr' | 'rtl';

Language Management

Resource Management

Loading, storing, and managing translation resources including namespaces, resource bundles, and dynamic resource loading.

function loadResources(callback?: (err: any) => void): void;
function addResource(lng: string, ns: string, key: string, value: string, options?: object): i18n;
function addResourceBundle(lng: string, ns: string, resources: any, deep?: boolean, overwrite?: boolean): i18n;

Resource Management

Plugin System

Extensible module system supporting backends, language detectors, formatters, post-processors, and third-party integrations.

function use<T extends Module>(module: T | NewableModule<T> | Newable<T>): i18n;

interface BackendModule<Options = object> extends Module {
  type: 'backend';
  init(services: Services, backendOptions: Options, i18nextOptions: InitOptions): void;
  read(language: string, namespace: string, callback: ReadCallback): void;
}

Plugin System

Global Functions

For convenience, i18next exports several commonly used functions directly:

const createInstance: typeof i18next.createInstance;
const init: typeof i18next.init;
const t: typeof i18next.t;
const changeLanguage: typeof i18next.changeLanguage;
const use: typeof i18next.use;
const exists: typeof i18next.exists;
const getFixedT: typeof i18next.getFixedT;
const loadResources: typeof i18next.loadResources;
const reloadResources: typeof i18next.reloadResources;
const loadNamespaces: typeof i18next.loadNamespaces;
const loadLanguages: typeof i18next.loadLanguages;
const setDefaultNamespace: typeof i18next.setDefaultNamespace;
const hasLoadedNamespace: typeof i18next.hasLoadedNamespace;
const dir: typeof i18next.dir;
const format: typeof i18next.format;

// Selector-based key extraction (TypeScript only)
function keyFromSelector<S = Record<string, any>, T = string>(
  selector: ($: S) => T
): T;

Core Types

interface i18n {
  // Core properties
  language: string;
  languages: readonly string[];
  resolvedLanguage?: string;
  options: InitOptions;
  modules: Modules;
  services: Services;
  store: ResourceStore;
  
  // Status properties
  isInitialized: boolean;
  isInitializing: boolean;
  initializedStoreOnce: boolean;
  initializedLanguageOnce: boolean;
  
  // Main translation function
  t: TFunction;
  
  // Format function for interpolation
  format: FormatFunction;
}

interface InitOptions {
  lng?: string;
  fallbackLng?: string | readonly string[] | FallbackLngObjList | ((code: string) => string | readonly string[] | FallbackLngObjList);
  ns?: string | readonly string[];
  defaultNS?: string | readonly string[];
  debug?: boolean;
  resources?: Resource;
  preload?: readonly string[];
  supportedLngs?: readonly string[];
  nonExplicitSupportedLngs?: boolean;
  load?: 'all' | 'currentOnly' | 'languageOnly';
  partialBundledLanguages?: boolean;
  interpolation?: InterpolationOptions;
  keySeparator?: string | false;
  nsSeparator?: string | false;
  pluralSeparator?: string;
  contextSeparator?: string;
  initAsync?: boolean;
  backend?: any;
  detection?: any;
  react?: ReactOptions;
  [key: string]: any;
}

interface TOptions {
  defaultValue?: string;
  lng?: string;
  lngs?: readonly string[];
  ns?: string | readonly string[];
  replace?: { [key: string]: any };
  count?: number;
  context?: string;
  skipInterpolation?: boolean;
  returnObjects?: boolean;
  joinArrays?: string;
  postProcess?: string | string[];
  keyPrefix?: string;
  [key: string]: any;
}

type TFunction = (
  key: string | string[],
  options?: TOptions
) => string;

type Callback = (error: any, t: TFunction) => void;

type FormatFunction = (value: any, format: string, lng: string, options: any) => string;

interface InterpolationOptions {
  escapeValue?: boolean;
  prefix?: string;
  suffix?: string;
  formatSeparator?: string;
  unescapePrefix?: string;
  unescapeSuffix?: string;
  nestingPrefix?: string;
  nestingSuffix?: string;
  maxReplaces?: number;
  skipOnVariables?: boolean;
  format?: FormatFunction;
}

interface ReactOptions {
  wait?: boolean;
  withRef?: boolean;
  bindI18n?: string;
  bindI18nStore?: string;
  transEmptyNodeValue?: string;
  transSupportBasicHtmlNodes?: boolean;
  transKeepBasicHtmlNodesFor?: readonly string[];
  useSuspense?: boolean;
}

interface Resource {
  [language: string]: {
    [namespace: string]: ResourceLanguage;
  };
}

interface ResourceLanguage {
  [key: string]: any;
}

interface FallbackLngObjList {
  [language: string]: readonly string[];
}

interface Services {
  backendConnector: any;
  i18nFormat: any;
  interpolator: Interpolator;
  languageDetector: any;
  languageUtils: any;
  logger: any;
  pluralResolver: any;
  resourceStore: ResourceStore;
  formatter?: Formatter;
}

interface Interpolator {
  init(options: InterpolationOptions, reset: boolean): undefined;
  reset(): undefined;
  resetRegExp(): undefined;
  interpolate(str: string, data: object, lng: string, options: InterpolationOptions): string;
  nest(str: string, fc: (...args: any[]) => any, options: InterpolationOptions): string;
}

interface Formatter {
  init(services: Services, i18nextOptions: InitOptions): void;
  add(name: string, fc: (value: any, lng: string | undefined, options: any) => string): void;
  addCached(name: string, fc: (lng: string | undefined, options: any) => (value: any) => string): void;
  format: FormatFunction;
}

interface ResourceStore {
  data: Resource;
  options: InitOptions;
  on(event: 'added' | 'removed', callback: (lng: string, ns: string) => void): void;
  off(event: 'added' | 'removed', callback?: (lng: string, ns: string) => void): void;
}