UNPKG

4.93 kBMarkdownView Raw
1# Introduction
2
3[![npm version](https://img.shields.io/npm/v/i18next-browser-languagedetector.svg?style=flat-square)](https://www.npmjs.com/package/i18next-browser-languagedetector)
4[![Bower](https://img.shields.io/bower/v/i18next-browser-languagedetector.svg)]()
5[![David](https://img.shields.io/david/i18next/i18next-browser-languagedetector.svg?style=flat-square)](https://david-dm.org/i18next/i18next-browser-languagedetector)
6
7This is a i18next language detection plugin use to detect user language in the browser with support for:
8
9- cookie (set cookie i18next=LANGUAGE)
10- sessionStorage (set key i18nextLng=LANGUAGE)
11- localStorage (set key i18nextLng=LANGUAGE)
12- navigator (set browser language)
13- querystring (append `?lng=LANGUAGE` to URL)
14- htmlTag (add html language tag <html lang="LANGUAGE" ...)
15- path (http://my.site.com/LANGUAGE/...)
16- subdomain (http://LANGUAGE.site.com/...)
17
18# Getting started
19
20Source can be loaded via [npm](https://www.npmjs.com/package/i18next-browser-languagedetector), bower or [downloaded](https://github.com/i18next/i18next-browser-languagedetector/blob/master/i18nextBrowserLanguageDetector.min.js) from this repo.
21
22```
23# npm package
24$ npm install i18next-browser-languagedetector
25
26# bower
27$ bower install i18next-browser-languagedetector
28```
29
30- If you don't use a module loader it will be added to `window.i18nextBrowserLanguageDetector`
31
32Wiring up:
33
34```js
35import i18next from 'i18next';
36import LanguageDetector from 'i18next-browser-languagedetector';
37
38i18next.use(LanguageDetector).init(i18nextOptions);
39```
40
41As with all modules you can either pass the constructor function (class) to the i18next.use or a concrete instance.
42
43## Detector Options
44*The default options can be found [here](https://github.com/i18next/i18next-browser-languageDetector/blob/9efebe6ca0271c3797bc09b84babf1ba2d9b4dbb/src/index.js#L11).*
45
46```js
47{
48 // order and from where user language should be detected
49 order: ['querystring', 'cookie', 'localStorage', 'sessionStorage', 'navigator', 'htmlTag', 'path', 'subdomain'],
50
51 // keys or params to lookup language from
52 lookupQuerystring: 'lng',
53 lookupCookie: 'i18next',
54 lookupLocalStorage: 'i18nextLng',
55 lookupSessionStorage: 'i18nextLng',
56 lookupFromPathIndex: 0,
57 lookupFromSubdomainIndex: 0,
58
59 // cache user language on
60 caches: ['localStorage', 'cookie'],
61 excludeCacheFor: ['cimode'], // languages to not persist (cookie, localStorage)
62
63 // optional expire and domain for set cookie
64 cookieMinutes: 10,
65 cookieDomain: 'myDomain',
66
67 // optional htmlTag with lang attribute, the default is:
68 htmlTag: document.documentElement,
69
70 // optional set cookie options, reference:[MDN Set-Cookie docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie)
71 cookieOptions: { path: '/', sameSite: 'strict' }
72}
73```
74
75Options can be passed in:
76
77**preferred** - by setting options.detection in i18next.init:
78
79```js
80import i18next from 'i18next';
81import LanguageDetector from 'i18next-browser-languagedetector';
82
83i18next.use(LanguageDetector).init({
84 detection: options,
85});
86```
87
88on construction:
89
90```js
91import LanguageDetector from 'i18next-browser-languagedetector';
92const languageDetector = new LanguageDetector(null, options);
93```
94
95via calling init:
96
97```js
98import LanguageDetector from 'i18next-browser-languagedetector';
99const languageDetector = new LanguageDetector();
100languageDetector.init(options);
101```
102
103## Adding own detection functionality
104
105### interface
106
107```js
108export default {
109 name: 'myDetectorsName',
110
111 lookup(options) {
112 // options -> are passed in options
113 return 'en';
114 },
115
116 cacheUserLanguage(lng, options) {
117 // options -> are passed in options
118 // lng -> current language, will be called after init and on changeLanguage
119 // store it
120 },
121};
122```
123
124### adding it
125
126```js
127import LanguageDetector from 'i18next-browser-languagedetector';
128const languageDetector = new LanguageDetector();
129languageDetector.addDetector(myDetector);
130
131i18next.use(languageDetector).init({
132 detection: options,
133});
134```
135
136Don't forget: You have to add the name of your detector (`myDetectorsName` in this case) to the `order` array in your `options` object. Without that, your detector won't be used. See the [Detector Options section for more](#detector-options).
137
138---
139
140<h3 align="center">Gold Sponsors</h3>
141
142<p align="center">
143 <a href="https://locize.com/" target="_blank">
144 <img src="https://raw.githubusercontent.com/i18next/i18next/master/assets/locize_sponsor_240.gif" width="240px">
145 </a>
146</p>
147
148---
149
150**localization as a service - locize.com**
151
152Needing a translation management? Want to edit your translations with an InContext Editor? Use the orginal provided to you by the maintainers of i18next!
153
154![locize](https://locize.com/img/ads/github_locize.png)
155
156With using [locize](http://locize.com/?utm_source=react_i18next_readme&utm_medium=github) you directly support the future of i18next and react-i18next.
157
158---