{"id":17620,"library":"express-locale","title":"Express Locale Middleware","description":"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.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/smhg/express-locale","tags":["javascript","locale","express","i18n","l10n","culture"],"install":[{"cmd":"npm install express-locale","lang":"bash","label":"npm"},{"cmd":"yarn add express-locale","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-locale","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for enabling the 'cookie' locale lookup source. You are responsible for setting the locale cookie value.","package":"cookie-parser","optional":true}],"imports":[{"note":"The `createLocaleMiddleware` function is the default export of the package. It works with both ESM `import` (via interop) and CommonJS `require`.","wrong":"import { createLocaleMiddleware } from 'express-locale';","symbol":"createLocaleMiddleware","correct":"import createLocaleMiddleware from 'express-locale';"},{"note":"For CommonJS environments, `createLocaleMiddleware` is the direct module export, not a named property.","wrong":"const { createLocaleMiddleware } = require('express-locale');","symbol":"createLocaleMiddleware (CommonJS)","correct":"const createLocaleMiddleware = require('express-locale');"}],"quickstart":{"code":"import express from 'express';\nimport createLocaleMiddleware from 'express-locale';\n\nconst app = express();\n\napp.use(createLocaleMiddleware({\n  priority: ['query', 'accept-language', 'default'],\n  default: 'en-US',\n  query: { name: 'lang' },\n  allowed: ['en-US', 'es-ES', 'fr-FR']\n}));\n\napp.get('/', (req, res) => {\n  // req.locale is an object with 'source', 'language', 'region'\n  // Its toString() method returns 'en-US' or similar\n  res.send(`Detected locale: ${req.locale.toString()} from ${req.locale.source}`);\n});\n\napp.listen(3000, () => {\n  console.log('Server running on http://localhost:3000');\n  console.log('Try: http://localhost:3000?lang=es-ES or set Accept-Language header');\n});","lang":"javascript","description":"This example demonstrates how to integrate `express-locale` middleware, configure lookup priority, set a default locale, and access the determined locale from `req.locale`."},"warnings":[{"fix":"Update any code that relies on locale identifiers being formatted with underscores. Input with underscores is still supported, but output will be hyphenated.","message":"Locale identifiers are now formatted using hyphens (e.g., 'en-US') instead of underscores ('en_US') to align with JavaScript's `Intl` object.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Express.js application to version 4.x or greater. For Express 3.x compatibility, use `express-locale` version 1.x.","message":"Express 3.x is no longer supported. The package now requires Express 4.x or newer.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Support for non-LTS/latest Node.js versions has been dropped. The package is now built without Babel, targeting modern Node.js environments.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"When using the 'cookie' lookup source, the `cookie-parser` middleware is required to be active *before* `express-locale` in your middleware chain.","severity":"gotcha","affected_versions":">=1.0.0"},{"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' }`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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');`.","cause":"Attempting to destructure a default export (e.g., `import { createLocaleMiddleware } from 'express-locale';` in ESM or `const { createLocaleMiddleware } = require('express-locale');` in CJS).","error":"TypeError: createLocaleMiddleware is not a function"},{"fix":"Ensure `app.use(createLocaleMiddleware(options))` is called before any route handlers or other middleware that attempt to access `req.locale`.","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.","error":"req.locale is undefined"},{"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' } }`.","cause":"The `hostname` lookup is included in the `priority` list, but no `hostname` configuration object (mapping hostnames to locales) has been provided.","error":"Invariant Violation: 'hostname' lookup is configured but no `hostname` map provided."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}