Express middleware to determine the locale identifier of the incomming request.
It returns (only) full locale identifiers based on the middleware's configuration. Configuration defines possible sources, their order and, optionally, a whitelist. For performance reasons, on each request, remaining lookups are ignored as soon as a match is found.
npm install --save express-locale
import express from 'express';
import createLocaleMiddleware from 'express-locale';
express()
.use(createLocaleMiddleware())
.use((req, res) => {
res.end(`Request locale: ${req.locale}`);
})
.listen(3000);The locale property on the request object will contain an object with these properties:
{
source: 'default',
language: 'en',
region: 'GB'
}When using this object in a string context, its toString method returns the locale identifier (en_GB in the example above).
Note: only full locales (language_REGION) are returned, but a mapping of languages to a default locale can be provided as a lookup.
You can pass a configuration object to createLocaleMiddleware() with the default being:
{
"priority": ["accept-language", "default"],
"default": "en_GB"
}This tells the middleware to use 2 sources in order: accept-language, which has no configuration, and default which is set to en_GB.
The name of the lookup used in the priority list always matches the configuration key.
Type: Array Default value ['accept-language', 'default']
Defines the order of lookups. The first lookup to return a full locale will be the final result.
Built-in lookups:
cookiequeryhostnameaccept-languagemapdefault
Read below on how to add custom lookups.
Type: Object Default value '{name: 'locale'}'
The name of the cookie that contains the locale for the cookie lookup.
Use with cookie-parser middleware.
Note: you are responsible for writing the locale to the cookie.
Type: Object Default value '{name: 'locale'}'
The name of the query string parameter that contains the locale for the query lookup.
Type: Object Default value {}
A mapping of hostnames to locales for the hostname lookup.
Type: Object Default value {}
Maps lookup results that return only a language to a full locale.
Type: String Default value 'en_GB'
The default locale for the default lookup.
Type: Array Default value undefined
Lookup results are validated against this list of allowed locales if provided.
Type: String Default value 'locale'
By default, the locale is attached to req.locale but can be configured with the requestProperty option.
Add custom lookups or overwrite the default ones by using the lookups property:
let localeMiddleware = createLocaleMiddleware({
priority: 'custom',
lookups: {
custom: (req) => req.ip === '127.0.0.1' ? 'en_US' : undefined;
}
});