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 |
|
7 | This 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 |
|
20 | Source 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 |
|
32 | Wiring up:
|
33 |
|
34 | ```js
|
35 | import i18next from 'i18next';
|
36 | import LanguageDetector from 'i18next-browser-languagedetector';
|
37 |
|
38 | i18next.use(LanguageDetector).init(i18nextOptions);
|
39 | ```
|
40 |
|
41 | As 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 |
|
75 | Options can be passed in:
|
76 |
|
77 | **preferred** - by setting options.detection in i18next.init:
|
78 |
|
79 | ```js
|
80 | import i18next from 'i18next';
|
81 | import LanguageDetector from 'i18next-browser-languagedetector';
|
82 |
|
83 | i18next.use(LanguageDetector).init({
|
84 | detection: options,
|
85 | });
|
86 | ```
|
87 |
|
88 | on construction:
|
89 |
|
90 | ```js
|
91 | import LanguageDetector from 'i18next-browser-languagedetector';
|
92 | const languageDetector = new LanguageDetector(null, options);
|
93 | ```
|
94 |
|
95 | via calling init:
|
96 |
|
97 | ```js
|
98 | import LanguageDetector from 'i18next-browser-languagedetector';
|
99 | const languageDetector = new LanguageDetector();
|
100 | languageDetector.init(options);
|
101 | ```
|
102 |
|
103 | ## Adding own detection functionality
|
104 |
|
105 | ### interface
|
106 |
|
107 | ```js
|
108 | export 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
|
127 | import LanguageDetector from 'i18next-browser-languagedetector';
|
128 | const languageDetector = new LanguageDetector();
|
129 | languageDetector.addDetector(myDetector);
|
130 |
|
131 | i18next.use(languageDetector).init({
|
132 | detection: options,
|
133 | });
|
134 | ```
|
135 |
|
136 | Don'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 |
|
152 | Needing 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 |
|
156 | With 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 | ---
|