![\"NPM](\"https://img.shields.io/npm/v/koa-i18next-detector.svg?style=flat-square\"\n)
\n \n \n ![\"Build](\"https://img.shields.io/github/actions/workflow/status/lxzxl/koa-i18next-detector/ci.yml?style=flat-square\"\n)
\n \n \n ![\"Downloads\"](\"https://img.shields.io/npm/dm/koa-i18next-detector.svg?style=flat-square\"\n)
\n \n \n ![\"License\"](\"https://img.shields.io/npm/l/koa-i18next-detector.svg?style=flat-square\"\n)
\n \n\n \n \n \n \n \n \n \n \n \n
\nAn i18next language detection plugin for Koa 2 and Koa 3.\n
\n\nDetects the request language from the querystring, URL path, cookie,\n`Accept-Language` header, or session — and can persist it back to a cookie or\nsession. Zero runtime dependencies, ships ESM + CJS with TypeScript types.\n\n## Install\n\n```sh\nnpm i koa-i18next-detector\n# or\npnpm add koa-i18next-detector\n```\n\nRequires Node.js >= 18. Compatible with i18next v19.6+ (tested against v26)\nand Koa 2/3.\n\n## Usage\n\n```ts\nimport i18next from 'i18next'\nimport LanguageDetector from 'koa-i18next-detector'\n// CJS: const { LanguageDetector } = require('koa-i18next-detector')\n\nawait i18next.use(LanguageDetector).init({\n fallbackLng: 'en',\n supportedLngs: ['en', 'es'],\n resources: {\n en: { translation: { key: 'hello world' } },\n es: { translation: { key: 'hola mundo' } },\n },\n detection: {\n // all options are optional; these are the defaults\n order: ['querystring', 'path', 'cookie', 'header', 'session'],\n\n lookupQuerystring: 'lng',\n\n lookupParam: 'lng', // for routes like '/:lng/result'\n lookupFromPathIndex: 0,\n\n lookupCookie: 'i18next',\n // cookieExpirationDate: new Date(), // default: now + 1 year\n // cookieDomain: '',\n // cookiePath: '/',\n // cookieSecure: true,\n // cookieSameSite: 'lax',\n // cookieHttpOnly: false,\n\n lookupSession: 'lng',\n\n // persist the detected language, e.g. ['cookie', 'session']\n caches: false,\n\n // convert detected codes, e.g. 'Iso15897' turns 'en-US' into 'en_US',\n // or pass a function: (lng) => lng.toLowerCase()\n // convertDetectedLanguage: 'Iso15897',\n },\n})\n\n// inside a Koa middleware:\nconst lng = i18next.services.languageDetector.detect(ctx)\ni18next.services.languageDetector.cacheUserLanguage(ctx, lng)\n```\n\nPair it with [koa-i18next-middleware](https://github.com/lxzxl/koa-i18next-middleware),\nwhich wires `detect`/`cacheUserLanguage` into the request lifecycle for you.\n\n### Custom detectors\n\n```ts\nimport { LanguageDetector } from 'koa-i18next-detector'\n\nconst lngDetector = new LanguageDetector()\nlngDetector.addDetector({\n name: 'mySessionDetector',\n\n lookup(ctx, options) {\n return ctx.session?.[options.lookupMySession]\n },\n\n cacheUserLanguage(ctx, lng, options) {\n if (ctx.session) ctx.session[options.lookupMySession] = lng\n },\n})\n\ni18next.use(lngDetector).init({\n detection: {\n order: ['mySessionDetector', 'querystring'],\n lookupMySession: 'lang',\n caches: ['mySessionDetector'],\n },\n})\n```\n\n### Built-in lookups\n\n| Name | Source | Can cache |\n| ------------- | -------------------------------------------------- | --------- |\n| `querystring` | `ctx.query[lookupQuerystring]` | – |\n| `path` | `ctx.params[lookupParam]` or path segment by index | – |\n| `cookie` | `ctx.cookies.get(lookupCookie)` | ✓ |\n| `header` | `Accept-Language` (ordered by `q` value) | – |\n| `session` | `ctx.session[lookupSession]` | ✓ |\n\nDetection stops at the first lookup that yields a language i18next reports as\nsupported (`supportedLngs`); otherwise `fallbackLng` is used. Detected values\nare screened against common XSS payloads before being passed to i18next.\n\n## Migrating from 0.x\n\n- Dual ESM/CJS package with TypeScript types. With `require`, use\n `const { LanguageDetector } = require('koa-i18next-detector')`.\n- Requires Node.js >= 18 and i18next >= 19.6 (the removed\n `isWhitelisted` API is no longer used).\n- The `cookies` package dependency was dropped; non-Koa contexts now fall back\n to parsing the `Cookie` header directly.\n- New options: `cookiePath`, `cookieSecure`, `cookieSameSite`,\n `cookieHttpOnly`, `convertDetectedLanguage`.\n- `addDetector` now throws a `TypeError` for detectors without a `name` or\n `lookup` and returns the detector instance for chaining.\n- Wildcard (`*`) entries in `Accept-Language` are ignored.\n\n## License\n\nMIT © [lxzxl](https://github.com/lxzxl)\n","readmeFilename":"README.md"}