Express middleware to determine locale
Last updated a year ago by smhg .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install express-locale 
SYNC missed versions from official npm registry.

Build Status express-locale

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.

Use version 1.x for Express 3 support and/or older Node versions.


npm install --save express-locale


import express from 'express';
import createLocaleMiddleware from 'express-locale';

  .use((req, res) => {
    res.end(`Request locale: ${req.locale}`);

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:

  • cookie
  • query
  • hostname
  • accept-language
  • map
  • default

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.

Custom lookups

Add custom lookups or overwrite the default ones by using the lookups property:

  priority: ['custom'],
  lookups: {
    custom: (req) => req.ip === '' ? 'en-US' : undefined

Current Tags

  • 2.0.0                                ...           latest (a year ago)

11 Versions

  • 2.0.0                                ...           a year ago
  • 1.2.0                                ...           a year ago
  • 1.1.0                                ...           a year ago
  • 1.0.5                                ...           3 years ago
  • 1.0.4                                ...           3 years ago
  • 1.0.2                                ...           3 years ago
  • 1.0.1                                ...           4 years ago
  • 1.0.0                                ...           4 years ago
  • 0.1.2                                ...           6 years ago
  • 0.1.1                                ...           6 years ago
  • 0.1.0                                ...           8 years ago

Copyright 2014 - 2016 © |