{"id":21241669,"url":"https://github.com/smhg/express-locale","last_synced_at":"2025-09-12T03:33:39.630Z","repository":{"id":7376328,"uuid":"8703308","full_name":"smhg/express-locale","owner":"smhg","description":"Express middleware to determine locale","archived":false,"fork":false,"pushed_at":"2025-01-10T14:30:19.000Z","size":107,"stargazers_count":24,"open_issues_count":1,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T15:11:11.205Z","etag":null,"topics":["express","express-middleware","i18n","internationalization","l10n","locale","localization"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smhg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-03-11T12:51:20.000Z","updated_at":"2025-01-21T21:38:26.000Z","dependencies_parsed_at":"2024-06-18T15:33:48.820Z","dependency_job_id":"2cd1fca7-d76c-48d2-8bb6-eda8c0deab62","html_url":"https://github.com/smhg/express-locale","commit_stats":{"total_commits":124,"total_committers":7,"mean_commits":"17.714285714285715","dds":"0.47580645161290325","last_synced_commit":"373d55ecfd37c15b770a8724ff5d5d43066b1724"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smhg%2Fexpress-locale","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smhg%2Fexpress-locale/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smhg%2Fexpress-locale/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smhg%2Fexpress-locale/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smhg","download_url":"https://codeload.github.com/smhg/express-locale/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247509237,"owners_count":20950232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","express-middleware","i18n","internationalization","l10n","locale","localization"],"created_at":"2024-11-21T00:56:37.239Z","updated_at":"2025-04-06T16:14:13.733Z","avatar_url":"https://github.com/smhg.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"express-locale [![CI](https://github.com/smhg/express-locale/actions/workflows/ci.yml/badge.svg)](https://github.com/smhg/express-locale/actions/workflows/ci.yml)\n==============\n\nExpress middleware to determine the [locale identifier](https://en.wikipedia.org/wiki/Locale_(computer_software)) of the incomming request.\n\nIt 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.\n\n\u003e Use version 1.x for Express 3 support and/or older Node versions.\n\n## Installation\n`npm install --save express-locale`\n\n## Usage\n```javascript\nimport express from 'express';\nimport createLocaleMiddleware from 'express-locale';\n\nexpress()\n  .use(createLocaleMiddleware())\n  .use((req, res) =\u003e {\n    res.end(`Request locale: ${req.locale}`);\n  })\n  .listen(3000);\n```\n\nThe `locale` property on the request object will contain an object with these properties:\n```json\n{\n\t\"source\": \"default\",\n\t\"language\": \"en\",\n\t\"region\": \"GB\"\n}\n```\nWhen using this object in a string context, its `toString` method returns the locale identifier (`en-GB` in the example above).\n\n**Note:** only full locales (language-REGION) are returned, but a [mapping](#map) of languages to a default locale can be provided as a lookup.\n\n\n## Configuration\nYou can pass a configuration object to `createLocaleMiddleware()` with the default being:\n```json\n{\n  \"priority\": [\"accept-language\", \"default\"],\n  \"default\": \"en-GB\"\n}\n```\nThis tells the middleware to use 2 sources in order: `accept-language`, which has no configuration, and `default` which is set to `en-GB`.\n\nThe name of the lookup used in the priority list always matches the configuration key.\n\n### Options\n\n* `priority` Array, default: `['accept-language', 'default']`\n\n  Defines the order of lookups. The first lookup to return a full locale will be the final result.\n\n  Built-in lookups:\n  * `cookie`\n  * `query`\n  * `hostname`\n  * `accept-language`\n  * `map`\n  * `default`\n\n  Read below on how to add custom lookups.\n\n* `allowed` Array\n\n  If provided, each lookup's results are validated against this whitelist.\n\n  \u003e **Note:** since this validation happens after each lookup, values which will still pass through the next lookup (like when using `map`) need to also be whitelisted as in the example below. This will likely be addressed in a future version (see [#20](https://github.com/smhg/express-locale/issues/20)).\n  ```javascript\n  // example\n  createLocaleMiddleware({\n    priority: ['accept-language', 'cookie', 'map'],\n    map: {\n      'en': 'en-US',\n      'fr': 'fr-CA'\n    },\n    allowed: ['en', 'fr', 'en-US', 'fr-CA']\n  });\n  ```\n\n* `requestProperty` String, default `'locale'`\n\n  The property on the request object (`req`) in which the locale is set.\n\n* `cookie` Object, default `'{name: 'locale'}'`\n\n  The `name` of the cookie that contains the locale for the cookie lookup.\n\n  Use with [cookie-parser](https://github.com/expressjs/cookie-parser) middleware.\n\n* `query` Object, default `'{name: 'locale'}'`\n\n  The `name` of the query string parameter that contains the locale for the query lookup.\n\n* `hostname` Object\n\n  A mapping of hostnames to locales for the hostname lookup.\n  ```javascript\n  // example\n  createLocaleMiddleware({\n    priority: ['hostname'],\n    map: {\n      'en.wikipedia.org': 'en-US',\n      'nl.wikipedia.org': 'nl-NL'\n    }\n  });\n  ```\n\n* `map` Object\n\n  Maps lookup results that return only a language to a full locale.\n  ```javascript\n  // example\n  createLocaleMiddleware({\n    priority: ['accept-language', 'cookie', 'map'],\n    map: {\n      'en': 'en-US',\n      'fr': 'fr-CA'\n    }\n  });\n  ```\n\n* `default` String, default `'en-GB'`\n\n  The default locale for the default lookup.\n\n* `lookups` Object\n \n  Add custom lookups or overwrite the default ones by using the `lookups` property.\n  ```javascript\n  // example\n  createLocaleMiddleware({\n    priority: ['custom'],\n    lookups: {\n      custom: (req) =\u003e req.ip === '127.0.0.1' ? 'en-US' : undefined\n    }\n  });\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmhg%2Fexpress-locale","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmhg%2Fexpress-locale","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmhg%2Fexpress-locale/lists"}