0
# i18next Browser Language Detector
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: i18next-browser-languagedetector
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install i18next-browser-languagedetector`
10

11
## Core Imports
12

13
```typescript
14
import I18nextBrowserLanguageDetector, { DetectorOptions, CustomDetector } from "i18next-browser-languagedetector";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const LanguageDetector = require("i18next-browser-languagedetector");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import i18next from "i18next";
27
import I18nextBrowserLanguageDetector from "i18next-browser-languagedetector";
28

29
// Initialize detector with options
30
const detector = new I18nextBrowserLanguageDetector(null, {
31
  order: ['querystring', 'cookie', 'localStorage', 'navigator'],
32
  lookupQuerystring: 'lng',
33
  lookupCookie: 'i18next',
34
  lookupLocalStorage: 'i18nextLng',
35
  caches: ['localStorage'],
36
  excludeCacheFor: ['cimode']
37
});
38

39
// Use with i18next
40
i18next
41
  .use(detector)
42
  .init({
43
    detection: {
44
      order: ['cookie', 'localStorage', 'navigator'],
45
      caches: ['localStorage', 'cookie']
46
    }
47
  });
48

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

53
// Cache a language
54
detector.cacheUserLanguage('en');
55
```
56

57
## Architecture
58

59
The library is built around several key components:
60

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

68
## Capabilities
69

70
### Language Detection
71

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

74
```typescript { .api }
75
class I18nextBrowserLanguageDetector {
76
  constructor(services?: any, options?: DetectorOptions);
77
  detect(detectionOrder?: DetectorOptions['order']): string | string[] | undefined;
78
}
79
```
80

81
[Language Detection](./detection.md)
82

83
### Configuration and Options
84

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

87
```typescript { .api }
88
interface DetectorOptions {
89
  /** Order and from where user language should be detected */
90
  order?: Array<'querystring' | 'cookie' | 'sessionStorage' | 'localStorage' | 'navigator' | 'htmlTag' | string>;
91
  
92
  /** Keys or params to lookup language from */
93
  lookupQuerystring?: string;
94
  lookupCookie?: string;
95
  lookupSessionStorage?: string;
96
  lookupLocalStorage?: string;
97
  lookupFromPathIndex?: number;
98
  lookupFromSubdomainIndex?: number;
99
  
100
  /** Cache user language on */
101
  caches?: string[];
102
  
103
  /** Languages to not persist (cookie, localStorage) */
104
  excludeCacheFor?: string[];
105
  
106
  /** Optional expire for set cookie (default: 10) */
107
  cookieMinutes?: number;
108
  
109
  /** Optional domain for set cookie */
110
  cookieDomain?: string;
111
  
112
  /** Optional cookie options */
113
  cookieOptions?: CookieOptions;
114
  
115
  /** Optional htmlTag with lang attribute (default: document.documentElement) */
116
  htmlTag?: HTMLElement | null;
117
  
118
  /** Optional conversion function to use to modify the detected language code */
119
  convertDetectedLanguage?: 'Iso15897' | ((lng: string) => string);
120
}
121
```
122

123
[Configuration](./configuration.md)
124

125
### Built-in Detector Modules
126

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

129
```typescript { .api }
130
interface CustomDetector {
131
  name: string;
132
  lookup(options: DetectorOptions): string | string[] | undefined;
133
  cacheUserLanguage?(lng: string, options: DetectorOptions): void;
134
}
135
```
136

137
[Detector Modules](./detectors.md)
138

139
### Language Caching
140

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

143
```typescript { .api }
144
class I18nextBrowserLanguageDetector {
145
  cacheUserLanguage(lng: string, caches?: string[]): void;
146
}
147
```
148

149
[Language Caching](./caching.md)
150

151
## Types
152

153
```typescript { .api }
154
interface CookieOptions {
155
  maxAge?: number;
156
  expires?: Date;
157
  httpOnly?: boolean;
158
  path?: string;
159
  domain?: string;
160
  secure?: boolean;
161
  sameSite?: boolean | 'lax' | 'strict' | 'none';
162
}
163

164
interface CustomDetector {
165
  name: string;
166
  cacheUserLanguage?(lng: string, options: DetectorOptions): void;
167
  lookup(options: DetectorOptions): string | string[] | undefined;
168
}
169

170
class I18nextBrowserLanguageDetector {
171
  type: 'languageDetector';
172
  detectors: { [key: string]: any };
173
  services: any;
174
  i18nOptions: any;
175
  
176
  constructor(services?: any, options?: DetectorOptions);
177
  addDetector(detector: CustomDetector): I18nextBrowserLanguageDetector;
178
  init(services?: any, options?: DetectorOptions, i18nOptions?: any): void;
179
  detect(detectionOrder?: DetectorOptions['order']): string | string[] | undefined;
180
  cacheUserLanguage(lng: string, caches?: string[]): void;
181
}
182
```