1 | # Introduction
|
2 |
|
3 | This is a middleware to use i18next in express.js.
|
4 |
|
5 | # Getting started
|
6 |
|
7 | Source can be loaded via [npm](https://www.npmjs.com/package/i18next-express-middleware).
|
8 |
|
9 | ```
|
10 | # npm package
|
11 | $ npm install i18next-express-middleware
|
12 | ```
|
13 |
|
14 | ## wire up i18next to request object
|
15 |
|
16 | ```js
|
17 | var i18next = require('i18next');
|
18 | var middleware = require('i18next-express-middleware');
|
19 | var express = require('express');
|
20 |
|
21 | i18next
|
22 | .use(middleware.LanguageDetector)
|
23 | .init({
|
24 | preload: ['en', 'de', 'it'],
|
25 | ...otherOptions
|
26 | });
|
27 |
|
28 | var app = express();
|
29 | app.use(middleware.handle(i18next, {
|
30 | ignoreRoutes: ["/foo"],
|
31 | removeLngFromUrl: false
|
32 | }));
|
33 |
|
34 |
|
35 | // in your request handler
|
36 | app.get('myRoute', function(req, res) {
|
37 | var lng = req.language; // 'de-CH'
|
38 | var lngs = req.languages; // ['de-CH', 'de', 'en']
|
39 | req.i18n.changeLanguage('en'); // will not load that!!! assert it was preloaded
|
40 |
|
41 | var exists = req.i18n.exists('myKey');
|
42 | var translation = req.t('myKey');
|
43 | });
|
44 |
|
45 | // in your views, eg. in pug (ex. jade)
|
46 | div=t('myKey')
|
47 | ```
|
48 |
|
49 | ## add routes
|
50 |
|
51 | ```js
|
52 | // missing keys
|
53 | app.post('/locales/add/:lng/:ns', middleware.missingKeyHandler(i18next));
|
54 |
|
55 | // multiload backend route
|
56 | app.get('/locales/resources.json', middleware.getResourcesHandler(i18next));
|
57 | ```
|
58 |
|
59 | ## add localized routes
|
60 |
|
61 | You can add your routes directly to the express app
|
62 |
|
63 | ```js
|
64 | var express = require('express'),
|
65 | app = express(),
|
66 | i18next = require('i18next'),
|
67 | FilesystemBackend = require('i18next-node-fs-backend'),
|
68 | i18nextMiddleware = require('i18next-express-middleware'),
|
69 | port = 3000;
|
70 |
|
71 | i18next
|
72 | .use(i18nextMiddleware.LanguageDetector)
|
73 | .use(FilesystemBackend)
|
74 | .init({ preload: ['en', 'de', 'it'], ...otherOptions }, function() {
|
75 | i18nextMiddleware.addRoute(i18next, '/:lng/key-to-translate', ['en', 'de', 'it'], app, 'get', function(req, res) {
|
76 | //endpoint function
|
77 | });
|
78 | });
|
79 | app.use(i18nextMiddleware.handle(i18next));
|
80 | app.listen(port, function() { console.log('Server listening on port', port) } );
|
81 | ```
|
82 |
|
83 | or to an express router
|
84 |
|
85 | ```js
|
86 | var express = require('express'),
|
87 | app = express(),
|
88 | i18next = require('i18next'),
|
89 | FilesystemBackend = require('i18next-node-fs-backend'),
|
90 | i18nextMiddleware = require('i18next-express-middleware'),
|
91 | router = require('express').Router(),
|
92 | port = 3000;
|
93 |
|
94 | i18next
|
95 | .use(i18nextMiddleware.LanguageDetector)
|
96 | .use(FilesystemBackend)
|
97 | .init({ preload: ['en', 'de', 'it'], ...otherOptions }, function() {
|
98 | i18nextMiddleware.addRoute(i18next, '/:lng/key-to-translate', ['en', 'de', 'it'], router, 'get', function(req, res) {
|
99 | //endpoint function
|
100 | });
|
101 | app.use('/', router);
|
102 | });
|
103 | app.use(i18nextMiddleware.handle(i18next));
|
104 | app.listen(port, function() { console.log('Server listening on port', port) } );
|
105 | ```
|
106 |
|
107 | ## language detection
|
108 |
|
109 | Detects user language from current request. Comes with support for:
|
110 |
|
111 | - path
|
112 | - cookie
|
113 | - header
|
114 | - querystring
|
115 | - session
|
116 |
|
117 | Wiring up:
|
118 |
|
119 | ```js
|
120 | var i18next = require('i18next');
|
121 | var middleware = require('i18next-express-middleware');
|
122 |
|
123 | i18next
|
124 | .use(middleware.LanguageDetector)
|
125 | .init(i18nextOptions);
|
126 | ```
|
127 |
|
128 | As with all modules you can either pass the constructor function (class) to the i18next.use or a concrete instance.
|
129 |
|
130 | ## Detector Options
|
131 |
|
132 | ```js
|
133 | {
|
134 | // order and from where user language should be detected
|
135 | order: [/*'path', 'session', */ 'querystring', 'cookie', 'header'],
|
136 |
|
137 | // keys or params to lookup language from
|
138 | lookupQuerystring: 'lng',
|
139 | lookupCookie: 'i18next',
|
140 | lookupSession: 'lng',
|
141 | lookupPath: 'lng',
|
142 | lookupFromPathIndex: 0,
|
143 |
|
144 | // cache user language
|
145 | caches: false, // ['cookie']
|
146 |
|
147 | // optional expire and domain for set cookie
|
148 | cookieExpirationDate: new Date(),
|
149 | cookieDomain: 'myDomain'
|
150 | }
|
151 | ```
|
152 |
|
153 | Options can be passed in:
|
154 |
|
155 | **preferred** - by setting options.detection in i18next.init:
|
156 |
|
157 | ```js
|
158 | var i18next = require('i18next');
|
159 | var middleware = require('i18next-express-middleware');
|
160 |
|
161 | i18next
|
162 | .use(middleware.LanguageDetector)
|
163 | .init({
|
164 | detection: options
|
165 | });
|
166 | ```
|
167 |
|
168 | on construction:
|
169 |
|
170 | ```js
|
171 | var middleware = require('i18next-express-middleware');
|
172 | var lngDetector = new middleware.LanguageDetector(null, options);
|
173 | ```
|
174 |
|
175 | via calling init:
|
176 |
|
177 | ```js
|
178 | var middleware = require('i18next-express-middleware');
|
179 |
|
180 | var lngDetector = new middleware.LanguageDetector();
|
181 | lngDetector.init(options);
|
182 | ```
|
183 |
|
184 | ## Adding own detection functionality
|
185 |
|
186 | ### interface
|
187 |
|
188 | ```js
|
189 | module.exports {
|
190 | name: 'myDetectorsName',
|
191 |
|
192 | lookup: function(req, res, options) {
|
193 | // options -> are passed in options
|
194 | return 'en';
|
195 | },
|
196 |
|
197 | cacheUserLanguage: function(req, res, lng, options) {
|
198 | // options -> are passed in options
|
199 | // lng -> current language, will be called after init and on changeLanguage
|
200 |
|
201 | // store it
|
202 | }
|
203 | };
|
204 | ```
|
205 |
|
206 |
|
207 | ### adding it
|
208 |
|
209 | ```js
|
210 | var i18next = require('i18next');
|
211 | var middleware = require('i18next-express-middleware');
|
212 |
|
213 | var lngDetector = new middleware.LanguageDetector();
|
214 | lngDetector.addDetector(myDetector);
|
215 |
|
216 | i18next
|
217 | .use(lngDetector)
|
218 | .init({
|
219 | detection: options
|
220 | });
|
221 | ```
|