A Fastify plugin to parse request language
Clone or download



js-standard-style Build Status Greenkeeper badge Known Vulnerabilities Coverage Status npm npm

Language parser plugin for fastify

It decorates req object with detectedLng and adds preHandler hook for those language parsers which you specified in order option. Supports cookie, header, query, path and session parser.


$ npm i --save fastify-language-parser


const fastify = require('fastify')()
const LP = require('fastify-language-parser')

  .reqister(LP, { order: ['query'] })
  .after(err => {
    if (err) throw err
    fastify.get('/', (req, reply) => {
      // GET /?lng=de will set req.detectedLng to 'de'
      reply.send({ detectedLng: req.detectedLng })

If you need different set of parsers for different routes, scope the routes and register this plugin in each scope where it needed.


General options

name type default description
fallbackLng {String} 'en' The default value of the req.detectedLng decorator.
order {Array} [] Order and from where language should be detected. The last item wins. Supported values are: cookie header path query session.
supportedLngs {Array} ['en'] Use this option to filter the parsed language code. If it is an empty array parsers will skip the filter step. The order of items only counts when you use header parser.

Parser specific options and notes

header parser

Under the hood it uses accept-language-parser. If supportedLngs does not contain any item it uses the parse, otherwise the pick method. Latter is the only case when the order in supportedLngs array makes any difference, because parser will pass it to the pick method. If the pick method returns no value than the detectedLng decorator will not change. It parses req.headers['accept-language'] value which provided by fastify and normally you don't need to change, but you can using the headerDecorator and headerKey options.

query & path parsers

Parses specified keys from req.query and req.params decorators which provided by fastify, so you don't need to change them, but you can using the pathDecorator and queryDecorator options.

name type default description
pathParam {String} 'lng' Parses the value of
queryString {String} 'lng' Parses the value of

cookie & session parsers

If you intend to use these parsers you need to register fastify-cookie or fastify-session plugin respectively. This plugin does not retrieves or sets any cookie or session value but looks for the req[decorator][key] value specified in options. The fastify-cookie plugin provides req.cookies decorator by defult. If you use fastify-session plugin you need to set the req[sessionDecorator][sessionKey] before this plugin, which reflects your session store state changes and provides the language code value.

name type default description
cookieDecorator {String} 'cookies' Looks for the key in
cookieKey {String} 'fastifyLanguageParser' Parses the value of
sessionDecorator {String} 'sessions' Looks for the key in
sessionKey {String} 'fastifyLanguageParser' Parses the value of


Licensed under MIT.