Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
131 lines (92 sloc) 4.15 KB


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.


$ 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.set('views', __dirname + '/views');
        app.set('view engine', 'ejs');
        // Lingua configuration
        app.use(lingua(app, {
            defaultLocale: 'en',
            path: __dirname + '/i18n'
        app.use(express.static(__dirname + '/public'));

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

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

Example Application

There is an example application at ./example

To run it:

$ cd example
$ node app.js

You can find a deployed version of this app here.


MIT License


Copyright (c) 2012, André König (Google+) (andre.koenig -[at]- gmail [dot] com)

Something went wrong with that request. Please try again.