Skip to content


Subversion checkout URL

You can clone with
Download ZIP
An i18n middleware for the Express.js framework.
JavaScript CSS
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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.