express-url-lang
v2.0.2
Published
Language-helper middleware for Express web server.
Downloads
4
Maintainers
Readme
express-mw-lang
Localization helper for Express web server.
Cuts off the language part from the path, and allow to use simple routes!
This middleware helps to determine the language, and handles urls of incoming requests for next middlewares. express-mw-lang
does not use Accept-Language
(but it is a good idea, to use the value of this HTTP-Header on first contact with the user, to predict his language).
To determine the language express-mw-lang
uses only URL of the request. Expected format of the URL:
schema://host/< LANG >/path?params
Sample URL, handled in French:
https://example.net/fr/article/1
As you could see - lang
is a first part of the path, and could be ommited, in this case the default language will be used.
Actually, express-mw-lang
acts and is an express-router. The best practice is appending your router/routes (use
/route
/get
/post
/...) to the express-mw-lang
, instead of habitual way with the Express-application itself.
See the Example section for more details.
Usage
Install:
$ npm install express-url-lang
Configure and use in the app.js
:
// ...
var langGen = require('express-url-lang');
var app = express();
// ...
let langmw = langGen();
langmw.esu(app);
Example
"use strict";
var express = require('express');
var logger = require('morgan'); // just for example, not required
var bodyParser = require('body-parser'); // just for example, not required
var langGen = require('express-url-lang');
var app = express();
app.use(logger());
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: false }));
// STEP 1: CREATING the middleware instance with options:
var langmw = langGen({
defaultLanguage: 'en',
availableLanguages: ['en', 'ru'],
});
// STEP 2: append middleware to application
// ( `esu` - is a reverse of `use`, because app and mw are swapped):
langmw.esu(app);
// appending main routes to the app (through lang-mw):
var router = express.Router();
router
.route('/home')
.get(function(req, res, next){
res.status(200).send('Hello [' + req.lang.code + ']');
});
// STEP 3: append your routes to lang-mw
langmw.use(router);
app.listen(3000, function() {
console.log('Example app listening on port 3000!');
});
// http://192.168.1.68:3000/en/home
// -> Hello [en]
// http://192.168.1.68:3000/ru/home
// -> Hello [ru]
// http://192.168.1.68:3000/home
// -> Hello [en]
Options
const options = {
defaultLanguage: 'en',
availableLanguages: [],
onLangDetected: function(langCode, req, res) {}
};
defaultLanguage
Default: 'en'
, string (ISO 639).
Default language
availableLanguages
Default: []
, array of strings (each string - ISO 639 code).
Languages, which will be recognized by middleware.
- Default language is always available
- For requests to unavailable language the response will contain redirect to the
/
of the site.
onLangDetected
Defalt: null
, function(langCode, req, res)
Callback, called when the lang is determined. Convenient place to setup the locale for momentjs
or choosen i18n library.
Example
var i18n = require("i18n")
var moment = require('moment')
// ...
let options = {
defaultLanguage: 'en',
availableLanguages: ['en', 'ru'],
onLangDetected: function(lang_code, req, res) {
i18n.setLocale(lang_code)
i18n.setLocale(req, lang_code)
i18n.setLocale(res, lang_code)
moment.locale(lang_code)
}
}
req
and res
extensions
This middleware extends the req
and res
objects with a lang
property, so extensions are:
req.lang
res.locals.lang
Further - description of the lang
object.
defaultLanguage
string, default language, taken from options.
available
array of available options. Each item is an object with code
-property (string, ISO 639)
usingDefault
bool indicates, that request is handled using default language (probably, there was an error, when the MW tried to determine the required language of the request).
routeTo
function(local_path, lang_code) , this function could help you to build paths to other pages of the site (taking the current language into account).
Notes about argument lang_code
:
- it is optional
- UNKNOWN/UNAVAILABLE lang_code - cause to use the default lang
- NULL lang_code - cause to use CURRENT lang (determined by MW from URL)
- EMPTY ('') lang_code - cause to use default lang!!
Contributing
You could take part in the development process, just follow this guideline.
License
Please, read the LICENSE
file in the root of the repository (or downloaded package).