i18next Middleware for Koa 2

Common errors

• TypeError: app.use is not a function

  cause The middleware is being used with a non-Koa application instance, or an older Koa 1.x application, which does not have the async `app.use` signature.
  fix Ensure your `app` object is an instance of `Koa()` from the `koa` package (version 2 or higher).

• TypeError: Cannot read properties of undefined (reading 'session') OR TypeError: ctx.session is undefined

  cause Session-based language detection methods (e.g., `lookupSession`, `lookupMySession`) are enabled in the `i18next` detection configuration, but a Koa session middleware (like `koa-session`) has not been installed or applied to the Koa app.
  fix Install `koa-session` (or your chosen session middleware) via `npm i koa-session` and then add `app.keys = ['your-secret-key']; app.use(session(app));` to your Koa application before applying `koa-i18next-middleware`.

• Error: i18next not initialized!

  cause The `i18next.init()` method was not called or did not complete its asynchronous initialization before `i18m.getHandler()` was invoked.
  fix Ensure `i18next.init()` is called and its callback indicates readiness, or use async/await with `i18next.init()` to guarantee initialization completes before the middleware handler is registered with `app.use()`.

• ReferenceError: require is not defined

  cause Attempting to use `const i18m = require('koa-i18next-middleware');` syntax in a pure ECMAScript Module (ESM) context (i.e., `"type": "module"` in `package.json` without a `require` shim).
  fix Use `import * as i18m from 'koa-i18next-middleware';` for ESM imports. Alternatively, if your project allows, revert to CommonJS by removing `"type": "module"` from `package.json`.

Warnings

• breaking This middleware is specifically designed for Koa 2 and requires Node.js versions that fully support async/await. It is not compatible with Koa 1.x or older Node.js runtimes.
  Fix: Ensure your project uses Koa 2.x or later and Node.js v7.6.0+ (or 8.x+ for full async/await support) or transpile your code.
• gotcha The `koa-i18next-middleware` project appears to be unmaintained. The last commit on its GitHub repository was approximately five years ago, and there have been no new releases since version 1.1.12. Users should be aware of the lack of ongoing support, bug fixes, or compatibility updates with newer Koa or Node.js versions. Consider `i18next-http-middleware` as a currently maintained alternative for Node.js frameworks like Koa.
  Fix: Proceed with caution. For new projects, evaluate more actively maintained alternatives like `i18next-http-middleware` (which can be used with Koa via `koaPlugin`). For existing projects, be prepared to fork or address compatibility issues manually.
• gotcha When enabling session-based language detection (e.g., `lookupSession`, `lookupMySession`), a separate Koa session middleware (e.g., `koa-session`) must be installed and configured *before* `koa-i18next-middleware` in your Koa application's middleware stack. Otherwise, `ctx.session` will be undefined, leading to errors.
  Fix: Install `koa-session` (or a similar session middleware) and configure it like `app.use(session(app))` before `app.use(i18m.getHandler(...))`.
• gotcha Configuring custom language detectors, as shown in the README, can be quite verbose and involves manually adding detector objects to the `i18m.LanguageDetector` instance. For simple use cases, this boilerplate might be excessive.
  Fix: For basic detection, rely on built-in `i18next` detection options (querystring, cookie, header) which require less setup. Only implement custom detectors when complex logic is necessary.

Install

• npm install koa-i18next-middleware npm
• yarn add koa-i18next-middleware yarn
• pnpm add koa-i18next-middleware pnpm

Imports

• koa-i18next-middleware
  wrong:

  import * as i18m from 'koa-i18next-middleware';

  correct:

  const i18m = require('koa-i18next-middleware');

  The package is primarily designed for CommonJS (`require`) usage. While ESM `import` might work via transpilation or bundlers, native ESM support is not guaranteed in older versions without explicit configuration.
• LanguageDetector
  wrong:

  import { LanguageDetector } from 'koa-i18next-middleware';

  correct:

  const lngDetector = new i18m.LanguageDetector();

  LanguageDetector is a named export from the main module. For ESM, prefer `import { LanguageDetector } from 'koa-i18next-middleware'` if the module exposes it this way, otherwise use `i18m.LanguageDetector` after a default import.
• getHandler
  wrong:

  app.use(getHandler(i18next, options));

  correct:

  app.use(i18m.getHandler(i18next, options));

  getHandler is a method exported from the main middleware module, not a top-level default export. It must be called on the imported `i18m` object.

Quickstart

This quickstart demonstrates how to initialize i18next, configure koa-i18next-middleware with a custom language detector, and apply it to a Koa 2 application, including session setup for detection.

const Koa = require('koa');
const i18next = require('i18next');
const i18m = require('koa-i18next-middleware');
const session = require('koa-session'); // Required for session-based detection

const app = new Koa();
app.keys = ['some secret key']; // Required for koa-session
app.use(session(app)); // Initialize session middleware

// Add custom detector.
const lngDetector = new i18m.LanguageDetector();
lngDetector.addDetector({
    name: 'mySessionDetector',
    lookup(ctx, options) {
        let found;
        if (options.lookupSession && ctx && ctx.session) {
            found = ctx.session[options.lookupMySession];
        }
        return found;
    },
    cacheUserLanguage(ctx, lng, options = {}) {
        if (options.lookupMySession && ctx && ctx.session) {
            ctx.session[options.lookupMySession] = lng;
        }
    }
});

i18next.use(lngDetector).init(
    {
        fallbackLng: 'en',
        preload: ['en', 'es'],
        resources: {
            en: {
                translation: {
                    key: 'hello world'
                }
            },
            es: {
                translation: {
                    key: 'es hello world es'
                }
            }
        },
        detection: {
            order: [
                'querystring',
                'path',
                'cookie',
                'session',
                'mySessionDetector'
            ],
            lookupQuerystring: 'lng',
            lookupParam: 'lng',
            lookupFromPathIndex: 0,
            lookupCookie: 'i18next',
            lookupSession: 'lng',
            lookupMySession: 'lang',
            caches: ['cookie', 'mySessionDetector']
        }
    },
    (err, t) => {
        if (err) return console.error('i18next initialization failed', err);
        console.log('i18next initialized. Example translation:', i18next.t('key'));
    }
);

app.use(
    i18m.getHandler(i18next, {
        locals: 'locals',
        ignoreRoutes: ['/no-lng-route']
    })
);

app.use(async ctx => {
    ctx.body = ctx.t('key'); // 'ctx.t' is provided by i18next
});

const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`Koa app listening on port ${port}`));