i18next-browser-languageDetector
Detects a visitor's language from cookies, storage, the URL, or the browser itself and wires it straight into i18next.
Repository Health
Technical Analysis
i18next-browser-languagedetector is the official i18next plugin for figuring out what language a browser visitor speaks, without you writing that logic yourself. It checks, in a configurable order, the query string, cookies, localStorage, sessionStorage, the navigator object, the <html lang> attribute, the URL path, subdomain, and URL hash, then hands the first (or best) match to i18next.
Register it once with i18next.use(LanguageDetector).init(...) and every subsequent page load or client-side navigation automatically resolves and caches the visitor’s language, with no server round-trip needed. Custom detection strategies can be added through the same addDetector interface the nine built-in detectors use.
What You Get
- Nine built-in browser-language detectors (cookie, querystring, localStorage, sessionStorage, navigator, htmlTag, path, subdomain, hash), each independently configurable and orderable
- Automatic caching of the resolved language back to cookies and/or localStorage so repeat visits skip re-detection
- A tiny
addDetector({name, lookup, cacheUserLanguage})interface for plugging in fully custom detection sources - Dual CJS/ESM builds with hand-maintained TypeScript declarations (
index.d.ts/index.d.mts) and ani18nextmodule augmentation for typeddetectionoptions - A built-in
hasXSSfilter that strips obviously malicious strings out of detected language values before they reach i18next
Common Use Cases
- Auto-selecting a locale on first visit to a client-rendered SPA based on the browser’s
navigator.language - Persisting a user’s manually-chosen language across sessions via cookie or localStorage caching
- Reading the language segment out of the URL path or subdomain for locale-prefixed routing (e.g.
/fr/pricingorfr.example.com) - Letting
?lng=dequery-string overrides win during QA/testing or shareable localized links
Under The Hood
Architecture The package exports a single Browser class (aliased LanguageDetector) implementing i18next’s LanguageDetectorModule interface (type: 'languageDetector'). On construction/init (src/index.js), it merges user options over sane defaults via a small utils.defaults helper, then registers nine built-in detector objects — cookie, querystring, localStorage, sessionStorage, navigator, htmlTag, path, subdomain, hash (each a standalone module in src/browserLookups/) — into a this.detectors map keyed by name. detect() walks the configured order array, calls each active detector’s lookup(options), flattens/dedupes results, filters out anything matching a small hasXSS regex blocklist, and applies an optional convertDetectedLanguage transform before returning the array to i18next (or a single string for i18next’s legacy synchronous API). cacheUserLanguage() mirrors this by fanning out to each cache-listed detector’s own cacheUserLanguage() method. Each detector module is self-contained with its own lookup/cacheUserLanguage pair, so adding a custom detector is just pushing another object with that shape via addDetector().
Tech Stack Plain ES module source with zero runtime dependencies beyond @babel/runtime (used only for helper injection during the build). Built via Rollup into CJS (dist/cjs) and ESM (dist/esm) targets, with a dual exports map in package.json wired for both require and import consumers, plus hand-written index.d.ts/index.d.mts declarations (the library is JS + Babel, not authored in TypeScript). Dev tooling is Mocha/expect.js for behavior tests and tsd for asserting the shipped .d.ts type-checks; ESLint (airbnb config) enforces style. i18next itself is a devDependency only, used to build a real i18next instance in tests.
Code Quality test/languageDetector.test.js (225 lines) exercises each detector individually against a real i18next instance, mocking global.document/global.window per test group — cookie, path, querystring, subdomain, storage, navigator, htmlTag, hash, cacheUserLanguage, and custom-detector registration. There’s no dedicated test for the hasXSS filter and no coverage reporting wired despite coveralls being a devDependency. Source style is consistent and each browserLookups/*.js file has a single clear responsibility; document.cookie access is guarded with try/catch at load time to survive non-browser environments, but individual lookups otherwise assume well-formed browser globals.
API Design The public surface is a single default-exported class matching i18next’s plugin contract exactly, so setup for anyone already on i18next is one line: i18next.use(LanguageDetector).init({...}). Options are a flat, well-documented object with sensible defaults, so most consumers never touch them. The addDetector interface for custom detectors mirrors the shape of the built-ins, making the extension model easy to learn from the source itself. A couple of legacy aliased options exist for backwards compatibility (e.g. lookupFromUrlIndex silently mapping to lookupFromPathIndex), adding minor cognitive overhead, but the README documents every option with inline defaults and a full custom-detector example.
Used by 49 apps in this directory
Activepieces
Automation · AI Assistants
Open-source AI automation platform that converts 280+ workflow integrations into MCP servers for LLMs, with no-code builders and TypeScript extensibility.
Apache Airflow
Data Engineering
Define, schedule, and monitor complex data workflows as Python code — with a powerful UI, 80+ provider integrations, and battle-tested scalability across thousands of production deployments.
AnythingLLM
Developer Tools · Automation · AI Assistants
The all-in-one AI platform for private document chat, no-code agents, and local LLMs with zero setup friction.
Authelia
Security · Authentication
OpenID Certified SSO and MFA portal for securing self-hosted web applications behind reverse proxies.
Banana Slides
AI Design Tools · Productivity
AI-native PPT generator with Vibe editing, multi-LLM support, and fully editable PPTX export
Blinko
Knowledge Management · Note Taking
A self-hosted, AI-powered card note-taking tool that lets you capture fleeting thoughts instantly and retrieve them with natural language search.
Chaskiq
CRM · Customer Support
Self-hosted live chat, video calls, help center, and marketing automation — a full-stack Intercom alternative you run on your own infrastructure.
ClearFlask
Product Management · Community
Open-source feedback management and roadmap tool that lets product teams collect, prioritize, and respond to user input — with AI-powered summarization and full self-hosting control.
Cosmos-Server
Security · Authentication
All-in-one self-hosted home server with SmartShield anti-DDoS, Nebula mesh VPN, automatic HTTPS, and a 250-app marketplace — all secured behind a unified auth layer.
