Express Locale Middleware

2.0.2 verified Thu Apr 23 auth: no javascript

express-locale is an Express.js middleware designed to robustly determine the locale identifier for incoming HTTP requests. It supports a configurable priority list of lookup sources, including `accept-language` headers, query parameters, cookies, hostname mappings, and a default fallback. Since version 2.0.0, the package standardizes locale output using hyphen-separated format (e.g., `en-US`), aligning with JavaScript's `Intl` object, while still supporting underscore-formatted input for backward compatibility. The current stable version is 2.0.2. While there isn't a strict rapid release cadence, the project receives maintenance updates. Its key differentiators include a flexible configuration for lookup order, the ability to define custom lookup functions, and a clear distinction between language-only and full locale identifiers, with an optional mapping feature, allowing for precise locale resolution based on application needs.

Common errors

error TypeError: createLocaleMiddleware is not a function ↓

cause Attempting to destructure a default export (e.g., `import { createLocaleMiddleware } from 'express-locale';` in ESM or `const { createLocaleMiddleware } = require('express-locale');` in CJS).

fix

Use a default import for ESM: import createLocaleMiddleware from 'express-locale';. For CJS, assign the module's export directly: const createLocaleMiddleware = require('express-locale');.

error req.locale is undefined ↓

cause The `express-locale` middleware has not been correctly added to the Express application's middleware chain, or it's accessed before the middleware has a chance to execute.

fix

Ensure app.use(createLocaleMiddleware(options)) is called before any route handlers or other middleware that attempt to access req.locale.

error Invariant Violation: 'hostname' lookup is configured but no `hostname` map provided. ↓

cause The `hostname` lookup is included in the `priority` list, but no `hostname` configuration object (mapping hostnames to locales) has been provided.

fix

Either remove 'hostname' from the priority array if not needed, or provide a hostname object in your middleware configuration, e.g., { hostname: { 'www.example.com': 'en-US' } }.

Warnings

breaking Locale identifiers are now formatted using hyphens (e.g., 'en-US') instead of underscores ('en_US') to align with JavaScript's `Intl` object. ↓

fix Update any code that relies on locale identifiers being formatted with underscores. Input with underscores is still supported, but output will be hyphenated.

breaking Express 3.x is no longer supported. The package now requires Express 4.x or newer. ↓

fix Upgrade your Express.js application to version 4.x or greater. For Express 3.x compatibility, use `express-locale` version 1.x.

breaking Support for non-LTS/latest Node.js versions has been dropped. The package is now built without Babel, targeting modern Node.js environments. ↓

fix Ensure your Node.js environment is an active LTS or the latest stable release. Older Node.js versions may require using `express-locale` version 1.x.

gotcha When using the 'cookie' lookup source, the `cookie-parser` middleware is required to be active *before* `express-locale` in your middleware chain. ↓

fix Install `cookie-parser` and ensure `app.use(cookieParser())` is called before `app.use(createLocaleMiddleware())`. You are also responsible for setting the actual locale cookie.

gotcha By default, `express-locale` only returns full locale identifiers (e.g., 'en-US'). If a lookup source provides only a language (e.g., 'en'), it will be ignored unless a `map` configuration is provided. ↓

fix To map language-only results to a full locale, provide a `map` object in your configuration, e.g., `map: { 'en': 'en-GB', 'fr': 'fr-FR' }`.

Install

npm install express-locale

yarn add express-locale

pnpm add express-locale

Imports

createLocaleMiddleware
wrong
```
import { createLocaleMiddleware } from 'express-locale';
```
correct
```
import createLocaleMiddleware from 'express-locale';
```
The `createLocaleMiddleware` function is the default export of the package. It works with both ESM `import` (via interop) and CommonJS `require`.
createLocaleMiddleware (CommonJS)
wrong
```
const { createLocaleMiddleware } = require('express-locale');
```
correct
```
const createLocaleMiddleware = require('express-locale');
```
For CommonJS environments, `createLocaleMiddleware` is the direct module export, not a named property.

Quickstart

This example demonstrates how to integrate `express-locale` middleware, configure lookup priority, set a default locale, and access the determined locale from `req.locale`.

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

const app = express();

app.use(createLocaleMiddleware({
  priority: ['query', 'accept-language', 'default'],
  default: 'en-US',
  query: { name: 'lang' },
  allowed: ['en-US', 'es-ES', 'fr-FR']
}));

app.get('/', (req, res) => {
  // req.locale is an object with 'source', 'language', 'region'
  // Its toString() method returns 'en-US' or similar
  res.send(`Detected locale: ${req.locale.toString()} from ${req.locale.source}`);
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Try: http://localhost:3000?lang=es-ES or set Accept-Language header');
});