fastify-language-parser

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.

Install

$ npm i --save fastify-language-parser

Versions

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

Example

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

fastify
  .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.

API

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 `req[cookieDecorator]`.
`cookieKey`	`{String}`	`'fastifyLanguageParser'`	Parses the value of `req[cookieDecorator][cookieKey]`.
`sessionDecorator`	`{String}`	`'sessions'`	Looks for the key in `req[sessionDecorator]`.
`sessionKey`	`{String}`	`'fastifyLanguageParser'`	Parses the value of `req[sessionDecorator][sessionKey]`.

License

Licensed under MIT.

lependu/fastify-language-parser