Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
An i18n middleware for the Express.js framework.
JavaScript CSS
branch: master
Failed to load latest commit information.
example Ported the example app to Express 4.0
lib Ported the example app to Express 4.0
.gitignore Fixed version number in package.json
CONTRIBUTORS.md Added CONTRIBUTORS file.
LICENSE
README.md Update README.md
package.json Ported the example app to Express 4.0

README.md

Lingua

Lingua is a middleware for the Express.js framework that helps you to internationalise your webapp easily. It determines the language of the user agent and pushes the i18n resources to your views.

Installation

$ npm install lingua

Quick Start

Using lingua comes down with four simple steps:

  1. Grab lingua

    var express = require('express'),
        lingua  = require('lingua');
    
    ...
    // Express init code goes here
    ...    
    
    // Express app configuration code and lingua init.
    app.configure(function() {
        ...
        app.set('views', __dirname + '/views');
        app.set('view engine', 'ejs');
    
        // Lingua configuration
        app.use(lingua(app, {
            defaultLocale: 'en',
            path: __dirname + '/i18n'
        }));
    
        app.use(express.bodyParser());
        app.use(express.methodOverride());
        app.use(express.static(__dirname + '/public'));
        app.use(app.router);
    
        ...
    });

    Note: Please ensure that the call: "app.use(app.router);" is the last entry in your configuration section.

  2. Create i18n resource files - Note that you have to create a resource file for your default language. (In this example: './i18n/en.json' and './i18n/de-de.json').

    // en.json
        {
            "title": "Hello World",
            "content": {
                "description": "A little description."
            }
        }
    
    // de-de.json
        {
            "title": "Hallo Welt",
            "content": {
                "description": "Eine kleine Beschreibung."
            }
        }
  3. a. Use lingua in your views - Static output - Note that the syntax depends on your template engine. In this example it is: ejs and the request comes from a browser which sends 'en' with the HTTP request header.

    <h1><%= lingua.title %></h1> <!-- out: <h1>Hello World</h1> -->
    <p><%= lingua.content.description %></h1> <!-- out: <p>A little description.</p> -->

    b. Use lingua in your views - Dynamic output - Sometimes it is necessary to handle dynamic data within your express route and pass it to the template. What if your i18n resource includes placeholders ("{key}") within a string where you can put in your dynamic data? Well, it is possible. First of all, look at this i18n resource file:

    // de.json
    {
        "greeting": "Hallo {name}. Dieser Schlüssel {code} wurde für Dich generiert."
    }

    Now it is possible to transfer an object from your route into your template:

    app.get('/', function(req, res) {
        var names = ['Sarah', 'Thomas', 'Claudia'];
    
        res.render('index', {
            person: {
                name: names[Math.floor(Math.random()*names.length)],
                code: Math.round(Math.random()*100)
            }
        });
    });

    And finally you can execute the i18n resource (yes, you can execute it (: ) and pass your data model to this function:

    <p><%= lingua.greeting(person) %></p>

    Note: Every i18n resource which contains placeholders like in the example above is a function after you've started the application.

  4. Let the user select a language - Note that the user's selection is persisted within a cookie. This is an optional step. If you want to let lingua determine the user language from the browser configuration then leave this step out. Anyway, this is a very handy feature for switching the language by a user decision.

    <a href="?language=de-DE">de-DE</a>
    <a href="?language=en-US">en-US</a>

    You can configure lingua in order to change the name of this parameter.

    // Express app configuration code and lingua init.
    app.configure(function() {
        ...
    
        // Lingua configuration
        app.use(lingua(app, {
            defaultLocale: 'en',
            path: __dirname + '/i18n',
            storageKey: 'lang' // http://domain.tld/?lang=de
        }));
    
        ...
    });

    The cookie lingua uses expires in one year, and includes the httpOnly flag to prevent clientside access from Javascript. You can override these settings by providing a cookieOptions key during configuration.

    // Express app configuration code and lingua init.
    app.configure(function() {
        ...
    
        // Lingua configuration
        app.use(lingua(app, {
            defaultLocale: 'en',
            path: __dirname + '/i18n',
            storageKey: 'lang', // http://domain.tld/?lang=de
            cookieOptions: {
                domain: '.domain.tld',    // to allow subdomains access to the same cookie, for instance
                path: '/blog',            // to restrict the language cookie to a path
                httpOnly: false,          // if you need access to this cookie from javascript on the client
                expires: new Date(Date.now() + 24 * 60 * 60 * 1000),  // expire in 1 day instead of 1 year
                secure: true              // for serving over https
            }
        }));
    
        ...
    });

Example Application

There is an example application at ./example

To run it:

$ cd example
$ npm i
$ node app.js

License

MIT License

Author

Copyright (c) 2013, André König

Something went wrong with that request. Please try again.