or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

caching.mdconfiguration.mddetection.mddetectors.mdindex.md
tile.json

index.mddocs/

i18next Browser Language Detector

i18next-browser-languagedetector is a comprehensive browser-based language detection library for the i18next internationalization framework. It provides multiple detection methods including cookie-based persistence, browser storage, navigator language settings, URL parameters, HTML attributes, and subdomain-based detection with configurable ordering and caching mechanisms.

Package Information

  • Package Name: i18next-browser-languagedetector
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: 
    npm install i18next-browser-languagedetector

Core Imports

import I18nextBrowserLanguageDetector, { DetectorOptions, CustomDetector } from "i18next-browser-languagedetector";

For CommonJS:

const LanguageDetector = require("i18next-browser-languagedetector");

Basic Usage

import i18next from "i18next";
import I18nextBrowserLanguageDetector from "i18next-browser-languagedetector";

// Initialize detector with options
const detector = new I18nextBrowserLanguageDetector(null, {
  order: ['querystring', 'cookie', 'localStorage', 'navigator'],
  lookupQuerystring: 'lng',
  lookupCookie: 'i18next',
  lookupLocalStorage: 'i18nextLng',
  caches: ['localStorage'],
  excludeCacheFor: ['cimode']
});

// Use with i18next
i18next
  .use(detector)
  .init({
    detection: {
      order: ['cookie', 'localStorage', 'navigator'],
      caches: ['localStorage', 'cookie']
    }
  });

// Manual detection
const detectedLanguage = detector.detect();
console.log('Detected language:', detectedLanguage);

// Cache a language
detector.cacheUserLanguage('en');

Architecture

The library is built around several key components:

  • Main Detector Class: 
    I18nextBrowserLanguageDetector
    implementing the i18next LanguageDetectorModule interface
  • Built-in Detectors: Eight specialized detector modules for different browser APIs and storage mechanisms
  • Configuration System: Flexible options for detection order, caching, and lookup parameters
  • Detection Chain: Sequential processing through configured detection methods until a language is found
  • Caching Layer: Automatic language persistence using browser storage mechanisms
  • Browser Compatibility: Automatic detection of available browser APIs, with cookie detection automatically disabled in environments where cookies are not accessible

Capabilities

Language Detection

Core language detection functionality that automatically identifies user's preferred language from multiple browser sources. Supports configurable detection order and fallback strategies.

class I18nextBrowserLanguageDetector {
  constructor(services?: any, options?: DetectorOptions);
  detect(detectionOrder?: DetectorOptions['order']): string | string[] | undefined;
}

Language Detection

Configuration and Options

Comprehensive configuration system for customizing detection behavior, caching strategies, and lookup parameters across all detection methods.

interface DetectorOptions {
  /** Order and from where user language should be detected */
  order?: Array<'querystring' | 'cookie' | 'sessionStorage' | 'localStorage' | 'navigator' | 'htmlTag' | string>;
  
  /** Keys or params to lookup language from */
  lookupQuerystring?: string;
  lookupCookie?: string;
  lookupSessionStorage?: string;
  lookupLocalStorage?: string;
  lookupFromPathIndex?: number;
  lookupFromSubdomainIndex?: number;
  
  /** Cache user language on */
  caches?: string[];
  
  /** Languages to not persist (cookie, localStorage) */
  excludeCacheFor?: string[];
  
  /** Optional expire for set cookie (default: 10) */
  cookieMinutes?: number;
  
  /** Optional domain for set cookie */
  cookieDomain?: string;
  
  /** Optional cookie options */
  cookieOptions?: CookieOptions;
  
  /** Optional htmlTag with lang attribute (default: document.documentElement) */
  htmlTag?: HTMLElement | null;
  
  /** Optional conversion function to use to modify the detected language code */
  convertDetectedLanguage?: 'Iso15897' | ((lng: string) => string);
}

Configuration

Built-in Detector Modules

Eight specialized detector modules for different browser APIs: cookie, querystring, localStorage, sessionStorage, navigator, htmlTag, path, and subdomain detection.

interface CustomDetector {
  name: string;
  lookup(options: DetectorOptions): string | string[] | undefined;
  cacheUserLanguage?(lng: string, options: DetectorOptions): void;
}

Detector Modules

Language Caching

Automatic language persistence system that stores detected languages in browser storage mechanisms to maintain user preferences across sessions.

class I18nextBrowserLanguageDetector {
  cacheUserLanguage(lng: string, caches?: string[]): void;
}

Language Caching

Types

interface CookieOptions {
  maxAge?: number;
  expires?: Date;
  httpOnly?: boolean;
  path?: string;
  domain?: string;
  secure?: boolean;
  sameSite?: boolean | 'lax' | 'strict' | 'none';
}

interface CustomDetector {
  name: string;
  cacheUserLanguage?(lng: string, options: DetectorOptions): void;
  lookup(options: DetectorOptions): string | string[] | undefined;
}

class I18nextBrowserLanguageDetector {
  type: 'languageDetector';
  detectors: { [key: string]: any };
  services: any;
  i18nOptions: any;
  
  constructor(services?: any, options?: DetectorOptions);
  addDetector(detector: CustomDetector): I18nextBrowserLanguageDetector;
  init(services?: any, options?: DetectorOptions, i18nOptions?: any): void;
  detect(detectionOrder?: DetectorOptions['order']): string | string[] | undefined;
  cacheUserLanguage(lng: string, caches?: string[]): void;
}