RingoJS

Module middleware/locale

This module provides middleware to find the user's locale

Functions

middleware (next, app)

This middleware gleans the locale based on various methods and puts it into the session. The goal is to get the exact locale that the user wants to use. However, this is not always possible, and there are a number of reasons why. This may include that user is not be logged in, or that the user's preferred locale is not supported by the current site, for example. Based on this, we order the methods of obtaining the locale according to how close they come to getting what the user actually wants.

The order is this:

  1. The user's actual preference. If you insert the locale into the session when the user logs in to your site based on the user's database entry, you will get the user's exact preference. If the locale is already set into the session, this middleware will not change it. It is up to your app to manage user authentication and user preferences.
  2. User's locale cookie for your site. If you use the cookies middleware and cookies are available on the request, this middleware will examine them to find the locale cookie and use it. If the locale cookie is not set, but the session response already has a locale, this middleware will set the locale cookie for use next time.
  3. Query parameters. If the URL or the POST data contain an explicit lang, language, or locale parameter, use that
  4. Accept-Language HTTP header. This middleware will examine the HTTP headers to see if there is a Accept-Language header. If found, it will run through the user's preferred languages in order against the list of locales that your site supports. If one matches, the locale set into the session. See the discussion below on how to set the list of locales that your site supports. If no list of supported locales is specified, this middleware will configure the first language it finds in the header.
  5. URL conventions. If your site uses simple conventions, this middleware can automatically extract the locale. The conventions that it looks for are:
    • http://<localename>.mysite.com/
    • http://www.mysite.com/<localename>/*
    • http://www.mysite.com/path?lang=<localename>
    • http://www.mysite.com/path?language=<localename>
    • http://www.mysite.com/path?locale=<localename>
    If your site uses a different convention, and that convention is simple and regular enough that the locale can be extracted from the URL using a regular expression, your app may specify that regular expression. See the discussion below on on how to set up this regular expression.
  6. Geolocation/IP to country lookup. This middleware does not do this, as it requires a paid back-end service to handle the requests.
  7. Site default from configuration. The default can be set from the a configuration file or the command-line arguments. This is the fallback locale if none of the above found a locale. See the description below on how to set the default.
  8. Last resort is the template source language. In this case, the locale in the session is set to "null" and the templates should not be translated at all.

To configure this middleware, the application instance is decorated with a function called "i18n" when it is configured. This function should be called and pass in an object that contains the settings. The properties in i18n can be any of:

  • supportedLocales - an array of locale specifiers that follow the BCP-47 convention. These locales should be as fully specified as possible with language, script, and region.
  • defaultLocale - a single locale specifier that follows the BCP-47 convention
  • domainregex - The regular expression to match against domain names to find the locale
  • domainmatchgroup - grouping within the domain regular expression that contains the locale
  • pathregex - The regular expression to match against the path to find the locale
  • pathmatchgroup - grouping within the path regular expression that contains the locale

Example

var {Application} = require('stick');
var app = exports.app = new Application();

app.configure('route');
app.configure('locale');
app.configure('cookies');
app.configure('params');
app.configure('session');

app.i18n({
    // might want to get this list from the configuration
    // so you can change it once for all your app server instances
    supportedLocales: [
        "en-US",
        "fr-FR",
        "it-IT",
        "de-DE",
        "es-ES",
        "pt-BR",
        "ja-JP",
        "ko-KR",
        "zh-Hans-CN",
        "zh-Hant-TW"
    ],
    defaultLocale: "en-US",   // get this from your configuration
    domainregex: "^(\w\w).mycompany.com",
    domainmatchgroup: 1 // this means that first parenthesized group contains the language/locale
    pathregex: "^/(\w\w)/.*",
    pathmatchgroup: 1 // this means that first parenthesized group contains the language/locale
});

Parameters

Function next

the wrapped middleware chain
Object app

the Stick Application object

Returns

Function

a JSGI middleware function

stick master

• Overview • Module Index