{"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,"search_vec":"'2.0.0':47 '2.0.2':83 'abil':109 'accept':33 'accept-languag':32 'align':62 'allow':132 'applic':139 'backward':76 'base':137 'cadenc':92 'clear':117 'compat':77 'configur':25,104 'cooki':38 'cultur':146 'current':79 'custom':112 'default':43 'defin':111 'design':11 'determin':14 'differenti':100 'distinct':118 'e.g':58 'en':60 'en-us':59 'express':1,5,143 'express-local':4 'express.js':9 'fallback':44 'featur':131 'flexibl':103 'format':57,73 'full':124 'function':114 'header':35 'hostnam':39 'http':20 'hyphen':55 'hyphen-separ':54 'i18n':144 'identifi':17,126 'includ':31,101 'incom':19 'input':74 'intl':66 'isn':86 'javascript':64,141 'key':99 'l10n':145 'languag':34,121 'language-on':120 'list':27 'local':2,6,16,51,125,135,142 'lookup':29,106,113 'mainten':96 'map':40,130 'middlewar':3,10 'need':140 'object':67 'option':129 'order':107 'output':52 'packag':49 'paramet':37 'precis':134 'prioriti':26 'project':94 'queri':36 'rapid':90 'receiv':95 'releas':91 'request':21 'resolut':136 'robust':13 'separ':56 'sinc':45 'sourc':30 'stabl':80 'standard':50 'still':69 'strict':89 'support':23,70 'underscor':72 'underscore-format':71 'updat':97 'us':61 'use':53 'version':46,81","created_at":"2026-04-23T17:47:14.750551+00:00","updated_at":"2026-04-23T17:47:14.750551+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/smhg/express-locale","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/express-locale","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-22","install_tag":null}}