i18next-browser-languageDetector

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 an i18next module augmentation for typed detection options
• A built-in hasXSS filter 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/pricing or fr.example.com)
• Letting ?lng=de query-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.