Registry / web-framework / express-locale

express-locale

library2.0.2jsnpmunverified

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.

web-framework http-networking

npm install express-locale

github ↗package ↗

INSTALL

IMPORT

SIG · EXPRESS-LOCALE

express-locale

web-frameworkjavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createLocaleMiddleware

✓ import createLocaleMiddleware from 'express-locale';

✗ 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)

✓ const createLocaleMiddleware = require('express-locale');

✗ const { createLocaleMiddleware } = require('express-locale');

For CommonJS environments, `createLocaleMiddleware` is the direct module export, not a named property.

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'); });

Debug

Known issues

breakingLocale 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.

affects: >=2.0.0

breakingExpress 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.

affects: >=2.0.0

breakingSupport 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.

affects: >=2.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaBy 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' }`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: createLocaleMiddleware is not a function

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');`.

req.locale is undefined

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`.

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

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' } }`.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

cookie-parseroptionalRequired for enabling the 'cookie' locale lookup source. You are responsible for setting the locale cookie value.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/smhg/express-locale ↗

packagehttps://www.npmjs.com/package/express-locale ↗