connect-locale
why?
because i18n can still be frustrating, when systems don't let you choose your language or location, but only guess what's best for you. connect-locale
gives you the flexibility to define your i18n strategy, as well as fallbacks if one strategy is not enough.
what does it do?
- this module provides flexible strategies to detect (get) and store the locale.
- it is not a full featured localization (i18n) solution that loads ressource files.
- it only detects and stores the best locale per request/response for the user,
- and it is good at it :-)
install
npm install connect-locale
note: if you want to the use
cookie
locale strategy, make sure you have loaded the cookie-parser middleware before this middleware, so that the cookie get's parsed and added to thereq.cookies
object.
use
these are the default options:
// require module
var Locale = require('connect-locale');
// add express/connect middleware with options object
app.use(Locale(options));
// e.g.
app.use(Locale({
// provided locales
locales: ['de', 'de-ch', 'en', 'en-GB', 'en-us'],
// strategies where to look for the locale:
// in this example, it looks first for the locale in the path, then in the cookie,
// and if it still didn't find it, it reads the users language/region preferences sent via the accept-language header.
getLocaleFrom: ['path', 'cookie', 'accept-language'],
// strategies where to store the locale:
// in this configuration it stores the locale in a cookie (to persist between requests),
// in the request object (helpful in other middlewares),
// and in the res.locals object (helpful in templates)
storeLocaleTo: ['cookie', 'request', 'locals']
}));
locale what?
locale
can be the short form of the language and can contain the region as well.
examples:
en
for englishen-GB
for english used in Great Britain
specifications:
locale strategies
With locale-connect, you can define several strategies to detect/get the requested locale by the user, and you can define several targets where the evaluated locale shall be stored.
get (getLocaleFrom)
the strategies are handled from left to right, until one strategy finds the locale.
available options:
path
: , it reads the locale from the url path:http://server:port/{locale}/rest/of/the/path
subdomain
: it reads the locale from the subdomain:https://{locale}.domain.com/path
,query
: it reads the locale from the url query: `www.mywebsite.com/home?{locale}cookie
: it reads the locale from the cookie. when previously stored.session
: it reads the locale from the session. when previously stored.accept-language
: it reads the users language/region preferences sent via the accept-language header.default
: it takes the first locale from thelocales
Array as the last fallback option.
store (storeLocaleTo)
the locale (if found) gets stored in the configured targets.
available options:
cookie
: it stores the locale in a cookie to persist for later requests.session
: it stores the locale in the session on the server side (which also requires a cookie for later requests).request
: it stores the locale in the request object. This might be helpful for use in following middlewares.locals
: it stores the locale in the res.locals object. This might be helpful for using the locale in the templates.
stored properties
connect-locale
stores the following properties to all the defined storeLocaleTo
targets:
locales
: array containing the supportedlocales
(optional)locale
: matchedlocale
requestedLocale
: requested locale detected via the given strategiesisPreferredLocale
:locale
is equalrequestedLocale
isSubLocale
: sub locale was matched e.g.en
instead ofen-GB
or vice versa.isAcceptLocale
: is in theaccept-language
header, but not the best option.isDefaultLocale
: is the default option (first defined locale in thelocales
Array).
options/api
locales
Array or comma separated String, default: undefined
- e.g. ['de', 'de-ch', 'en', 'en-GB', 'en-us']
- This is the definition of the supported locales (optional).
- If this option is omitted, it accetps the first locale that is detected with the given
getLocaleFrom
Strategy definition.
getLocaleFrom
Array or comma separated String, default: undefined
- Available Strategies: ['path', 'subdomain', 'query', 'cookie', 'session', 'accept-language']
- Mandatory Locale Detection Strategy Array.
- The provided strategies are processed from left to right until a locale matches
- if no
locales
definitions are provided, it just returns the first locale it finds
storeLocaleTo
Array or comma separated String, default: empty Array
- Available Strategies: ['cookie', 'session', 'request', 'locals']
- Mandatory Locale Storage Strategy Array.
- The provided strategies are always processed from left to right
- if no locale was found, nothing get's stored
matchSubTags
Boolean, default: true
- SubTags are detected.
- the requested
de-CH
matches the definedde
Locale, ifde-CH
is not defined. - turn this option off (false), if you want to match only the exact locales. e.g.
path
Function, default: req.path
- provide a specific path function if you get the locale with the
path
strategy, but don't want the path to be based on req.path.
path : function(req) {
var url = require('url');
return url.parse(req.originalUrl);
}
strategies
Object, default: all strategies from path './lib/stragety'
- if you want to provide additional stategies, have a look how to implement it in the './lib/stragety' folder.
- provide an object with the additional strategies in the form: {strategyName: strategy}
queryLocaleName
String, default: 'lang'
- url query parameter name. example:
localhost?lang=de
cookieLocaleName
String, default: 'lang'
- cookie name
cookie
Object, default: undefined
- cookie options: see: http://expressjs.com/4x/api.html#res.cookie
persistLocales
Boolean, default: true
- determines whether to include array of locales in persisted locale object
test
npm test
credits
- the
accept-language
uses the great negotiator/language module. - the other
strategies
were extracted from loc.
license
MIT