Skip to content


Repository files navigation


js-standard-style Build Status Known Vulnerabilities Coverage Status npm (scoped) 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


The plugin supports the following Fastify versions. Please refer to the corresponding branch in PR and issues.

Version Branch Fastify End of Support
1.x 1.x 1.x EOL
2.x 2.x 2.x TBD
3.x master 3.x TBD


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

  .register(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's core Request object. Ususally you don't need to change them, but you can using the pathDecorator and queryDecorator options.

name type default description
pathDecorator {String} 'params' The object key which contains the params matching the URL.
pathKey {String} lng The object key which contains the actual language within the req[pathDecorator] object.
queryDecorator {String} 'query' The object key which contains the parsed querystring.
queryKey {String} lng The object key which contains the actual language within the querystring.

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.


A Fastify plugin to parse request language








No packages published

Contributors 4