Introduction

This is a middleware to be used with Node.js web frameworks like express or Fastify and also for Deno.

It's based on the deprecated i18next-express-middleware and can be used as a drop-in replacement. It's not bound to a specific http framework anymore.

Getting started

# npm package
$ npm install i18next-http-middleware

wire up i18next to request object

1var i18next = require('i18next')
2var middleware = require('i18next-http-middleware')
3var express = require('express')
4
5i18next.use(middleware.LanguageDetector).init({
6  preload: ['en', 'de', 'it'],
7  ...otherOptions
8})
9
10var app = express()
11app.use(
12  middleware.handle(i18next, {
13    ignoreRoutes: ['/foo'] // or function(req, res, options, i18next) { /* return true to ignore */ }
14  })
15)
16
17// in your request handler
18app.get('myRoute', (req, res) => {
19  var lng = req.language // 'de-CH'
20  var lngs = req.languages // ['de-CH', 'de', 'en']
21  req.i18n.changeLanguage('en') // will not load that!!! assert it was preloaded
22
23  var exists = req.i18n.exists('myKey')
24  var translation = req.t('myKey')
25})
26
27// in your views, eg. in pug (ex. jade)
28div = t('myKey')

Fastify usage

1var i18next = require('i18next')
2var middleware = require('i18next-http-middleware')
3var fastify = require('fastify')
4
5i18next.use(middleware.LanguageDetector).init({
6  preload: ['en', 'de', 'it'],
7  ...otherOptions
8})
9
10var app = fastify()
11app.register(i18nextMiddleware.plugin, {
12  i18next,
13  ignoreRoutes: ['/foo'] // or function(req, res, options, i18next) { /* return true to ignore */ }
14})
15// or
16// app.addHook('preHandler', i18nextMiddleware.handle(i18next, {
17//   ignoreRoutes: ['/foo'] // or function(req, res, options, i18next) { /* return true to ignore */ }
18// }))
19
20// in your request handler
21app.get('myRoute', (request, reply) => {
22  var lng = request.language // 'de-CH'
23  var lngs = v.languages // ['de-CH', 'de', 'en']
24  request.i18n.changeLanguage('en') // will not load that!!! assert it was preloaded
25
26  var exists = request.i18n.exists('myKey')
27  var translation = request.t('myKey')
28})

Deno usage

abc

1import i18next from 'https://deno.land/x/i18next/index.js'
2import Backend from 'https://cdn.jsdelivr.net/gh/i18next/i18next-fs-backend/index.js'
3import i18nextMiddleware from 'https://deno.land/x/i18next_http_middleware/index.js'
4import { Application } from 'https://deno.land/x/abc/mod.ts'
5import { config } from "https://deno.land/x/dotenv/dotenv.ts";
6
7i18next
8  .use(Backend)
9  .use(i18nextMiddleware.LanguageDetector)
10  .init({
11    // debug: true,
12    backend: {
13      // eslint-disable-next-line no-path-concat
14      loadPath: 'locales/{{lng}}/{{ns}}.json',
15      // eslint-disable-next-line no-path-concat
16      addPath: 'locales/{{lng}}/{{ns}}.missing.json'
17    },
18    fallbackLng: 'en',
19    preload: ['en', 'de']
20  })
21
22const port = config.PORT || 8080
23const app = new Application()
24const handle = i18nextMiddleware.handle(i18next)
25app.use((next) =>
26  (c) => {
27    handle(c.request, c.response, () => {})
28    return next(c)
29  }
30)
31app.get('/', (c) => c.request.t('home.title'))
32await app.start({ port })

ServestJS

1import i18next from 'https://deno.land/x/i18next/index.js'
2import Backend from 'https://cdn.jsdelivr.net/gh/i18next/i18next-fs-backend/index.js'
3import i18nextMiddleware from 'https://deno.land/x/i18next_http_middleware/index.js'
4import { createApp } from 'https://servestjs.org/@v1.0.0-rc2/mod.ts'
5import { config } from "https://deno.land/x/dotenv/dotenv.ts";
6
7i18next
8  .use(Backend)
9  .use(i18nextMiddleware.LanguageDetector)
10  .init({
11    // debug: true,
12    backend: {
13      // eslint-disable-next-line no-path-concat
14      loadPath: 'locales/{{lng}}/{{ns}}.json',
15      // eslint-disable-next-line no-path-concat
16      addPath: 'locales/{{lng}}/{{ns}}.missing.json'
17    },
18    fallbackLng: 'en',
19    preload: ['en', 'de']
20  })
21
22const port = config.PORT || 8080
23const app = createApp()
24app.use(i18nextMiddleware.handle(i18next))
25app.get('/', async (req) => {
26  await req.respond({
27    status: 200,
28    headers: new Headers({
29      'content-type': 'text/plain',
30    }),
31    body: req.t('home.title')
32  })
33})
34await app.listen({ port })

add routes

1// missing keys make sure the body is parsed (i.e. with [body-parser](https://github.com/expressjs/body-parser#bodyparserjsonoptions))
2app.post('/locales/add/:lng/:ns', middleware.missingKeyHandler(i18next))
3
4// multiload backend route
5app.get('/locales/resources.json', middleware.getResourcesHandler(i18next))

add localized routes

You can add your routes directly to the express app

1var express = require('express'),
2  app = express(),
3  i18next = require('i18next'),
4  FilesystemBackend = require('i18next-fs-backend'),
5  i18nextMiddleware = require('i18next-http-middleware'),
6  port = 3000
7
8i18next
9  .use(i18nextMiddleware.LanguageDetector)
10  .use(FilesystemBackend)
11  .init({ preload: ['en', 'de', 'it'], ...otherOptions }, () => {
12    i18nextMiddleware.addRoute(
13      i18next,
14      '/:lng/key-to-translate',
15      ['en', 'de', 'it'],
16      app,
17      'get',
18      (req, res) => {
19        //endpoint function
20      }
21    )
22  })
23app.use(i18nextMiddleware.handle(i18next))
24app.listen(port, () => {
25  console.log('Server listening on port', port)
26})

or to an express router

1var express = require('express'),
2  app = express(),
3  i18next = require('i18next'),
4  FilesystemBackend = require('i18next-fs-backend'),
5  i18nextMiddleware = require('i18next-http-middleware'),
6  router = require('express').Router(),
7  port = 3000
8
9i18next
10  .use(i18nextMiddleware.LanguageDetector)
11  .use(FilesystemBackend)
12  .init({ preload: ['en', 'de', 'it'], ...otherOptions }, () => {
13    i18nextMiddleware.addRoute(
14      i18next,
15      '/:lng/key-to-translate',
16      ['en', 'de', 'it'],
17      router,
18      'get',
19      (req, res) => {
20        //endpoint function
21      }
22    )
23    app.use('/', router)
24  })
25app.use(i18nextMiddleware.handle(i18next))
26app.listen(port, () => {
27  console.log('Server listening on port', port)
28})

custom http server

Define your own functions to handle your custom request or response

1middleware.handle(i18next, {
2  getPath: (req) => req.path,
3  getUrl: (req) => req.url,
4  setUrl: (req, url) => req.url = url,
5  getQuery: (req) => req.query,
6  getParams: (req) => req.params,
7  getBody: (req) => req.body,
8  setHeader: (res, name, value) => res.setHeader(name, value),
9  setContentType: (res, type) => res.contentType(type),
10  setStatus: (res, code) => res.status(code),
11  send: (res, body) => res.send(body)
12})

language detection

Detects user language from current request. Comes with support for:

• path
• cookie
• header
• querystring
• session

Wiring up:

1var i18next = require('i18next')
2var middleware = require('i18next-http-middleware')
3
4i18next.use(middleware.LanguageDetector).init(i18nextOptions)

As with all modules you can either pass the constructor function (class) to the i18next.use or a concrete instance.

Detector Options

1{
2  // order and from where user language should be detected
3  order: [/*'path', 'session', */ 'querystring', 'cookie', 'header'],
4
5  // keys or params to lookup language from
6  lookupQuerystring: 'lng',
7  lookupCookie: 'i18next',
8  lookupHeader: 'accept-language',
9  lookupSession: 'lng',
10  lookupPath: 'lng',
11  lookupFromPathIndex: 0,
12
13  // cache user language
14  caches: false, // ['cookie']
15
16  // optional expire and domain for set cookie
17  cookieExpirationDate: new Date(),
18  cookieDomain: 'myDomain',
19  cookiePath: '/my/path',
20  cookieSecure: true, // if need secure cookie
21  cookieSameSite: 'strict' // 'strict', 'lax' or 'none'
22}

Options can be passed in:

preferred - by setting options.detection in i18next.init:

1var i18next = require('i18next')
2var middleware = require('i18next-http-middleware')
3
4i18next.use(middleware.LanguageDetector).init({
5  detection: options
6})

on construction:

1var middleware = require('i18next-http-middleware')
2var lngDetector = new middleware.LanguageDetector(null, options)

via calling init:

1var middleware = require('i18next-http-middleware')
2
3var lngDetector = new middleware.LanguageDetector()
4lngDetector.init(options)

Adding own detection functionality

interface

1module.exports = {
2  name: 'myDetectorsName',
3
4  lookup: function(req, res, options) {
5    // options -> are passed in options
6    return 'en'
7  },
8
9  cacheUserLanguage: function(req, res, lng, options) {
10    // options -> are passed in options
11    // lng -> current language, will be called after init and on changeLanguage
12
13    // store it
14  }
15}

adding it

1var i18next = require('i18next')
2var middleware = require('i18next-http-middleware')
3
4var lngDetector = new middleware.LanguageDetector()
5lngDetector.addDetector(myDetector)
6
7i18next.use(lngDetector).init({
8  detection: options
9})

---

Gold Sponsors