Noodles, Poodles and More!

    express-locale
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/express-locale package

    2.0.1 • Public • Published

    express-locale CI

    Express middleware to determine the locale identifier of the incomming request.

    It returns (only) full locale identifiers based on the middleware's configuration. Configuration defines possible sources, their order and, optionally, a whitelist. For performance reasons, on each request, remaining lookups are ignored as soon as a match is found.

    Use version 1.x for Express 3 support and/or older Node versions.

    Installation

    npm install --save express-locale

    Usage

    import express from 'express';
    import createLocaleMiddleware from 'express-locale';
    
    express()
      .use(createLocaleMiddleware())
      .use((req, res) => {
        res.end(`Request locale: ${req.locale}`);
      })
      .listen(3000);

    The locale property on the request object will contain an object with these properties:

    {
    	"source": "default",
    	"language": "en",
    	"region": "GB"
    }

    When using this object in a string context, its toString method returns the locale identifier (en-GB in the example above).

    Note: only full locales (language-REGION) are returned, but a mapping of languages to a default locale can be provided as a lookup.

    Configuration

    You can pass a configuration object to createLocaleMiddleware() with the default being:

    {
      "priority": ["accept-language", "default"],
      "default": "en-GB"
    }

    This tells the middleware to use 2 sources in order: accept-language, which has no configuration, and default which is set to en-GB.

    The name of the lookup used in the priority list always matches the configuration key.

    priority

    Type: Array Default value ['accept-language', 'default']

    Defines the order of lookups. The first lookup to return a full locale will be the final result.

    Built-in lookups:

    • cookie
    • query
    • hostname
    • accept-language
    • map
    • default

    Read below on how to add custom lookups.

    cookie

    Type: Object Default value '{name: 'locale'}'

    The name of the cookie that contains the locale for the cookie lookup.

    Use with cookie-parser middleware.

    Note: you are responsible for writing the locale to the cookie.

    query

    Type: Object Default value '{name: 'locale'}'

    The name of the query string parameter that contains the locale for the query lookup.

    hostname

    Type: Object Default value {}

    A mapping of hostnames to locales for the hostname lookup.

    map

    Type: Object Default value {}

    Maps lookup results that return only a language to a full locale.

    default

    Type: String Default value 'en-GB'

    The default locale for the default lookup.

    allowed

    Type: Array Default value undefined

    Lookup results are validated against this list of allowed locales if provided.

    requestProperty

    Type: String Default value 'locale'

    By default, the locale is attached to req.locale but can be configured with the requestProperty option.

    Custom lookups

    Add custom lookups or overwrite the default ones by using the lookups property:

    createLocaleMiddleware({
      priority: ['custom'],
      lookups: {
        custom: (req) => req.ip === '127.0.0.1' ? 'en-US' : undefined
      }
    });

    Install

    npm i express-locale

    DownloadsWeekly Downloads

    5,206

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    15.3 kB

    Total Files

    13

    Last publish

    Collaborators

    • smhg