Express i18n with handlebars and maintainable links

3 min readApr 18, 2016

Nowadays almost every new website points towards a global market, if you are one of these new sites you want to deliver your message to every person in the world in a clear and efficient way. One of the first barriers that block your message from getting to your user correctly is the language, in order to avoid the problem of rewriting your app for each language there are techniques like internationalization, or i18n for short, that help avoid this problem. i18n consists of making every text in your site a variable and every time the page is requested in certain language, every variable grabs its value from a dictionary for each of the languages it is targeted.

It is fairly quick to implement this technique in an express project, but handlebars is not supported out of the box by the i18n module, so Ill explain how to implement it. Ill assume basic understanding of a express or node application.

For starters we’ll need to install via npm the following packages:

npm install express3-handlebars i18n

After installing them we need to setup our application to use the internationalization module with a basic configuration and we also need to specify our templating engine configuration to use handlebars engine with our configuration:

app.js//Our express application
var express = require(‘express’);
var app = express();..//The i18n module is loaded
var i18n = require(‘i18n’);..//Load handlebars engine and load our configuration from the file hbsconf.js under a libs folder at the same level of the application
var handlebars = require(‘express3-handlebars’).create(require(‘./libs/hbsconf.js’));//Configure i18n module with a minimal configuration
i18n.configure({
    locales: [‘es’,’en’], 
    //List of available languages
   
    cookie: ‘locale’, 
    //Name of the cookie this preference is going to be stored    directory: __dirname + “/locales”, 
    //Where the dictionaries will be stored
    //(This directory and the available dictionary JSON files are generated by the module automatically)    defaultLocale: ‘es’, 
    //Which will be the default language loaded if the language requested by the browser is not available
});..//Set our application to use our configured handlebars module as the view engine 
app.engine(‘handlebars’, handlebars.engine);
app.set(‘view engine’, ‘handlebars’);//Set our application to use our configuration of the i18n module
app.use(i18n.init);//Rest of the application
..
..

At this point we only need to configure our handlebars helpers in order to use them on our templates, but since it is the same idea Ill teach you how to make more maintainable urls through your templates. This will help you in case you wish to change the urls of all your pages, you will only need to change them once.
For this we will need to manually create a JSON file which will map a name or tag to a URL, just like the i18n module created.

urls.json{
 “home”        : ”/”,
 “userProfile” : ”/user/profile/”,
 “contact”     : ”/contact”,
 “about”       : ”/about”
}hbsconf.js//Handlebars configuration
//Load i18n module and our urls.json dictionary from the same folder that our controllers are (just to keep them in an easy to remember place)
var i18n = require(‘i18n’);
var urls = require(‘../controllers/urls.json’);module.exports = {
    //Setup our default layout
    defaultLayout: ‘main’,
 
    //More handlebars configuration
    ..
 
    //Register handlebars helpers
  helpers: {
    //Register your helpers
    ..
    ..
    //Helper for multiple languages
    i18n: function(){
        return i18n.__.apply(this,arguments);
    },
    //This helper is part of i18n and it is used for multiple languages for plural and singular. Check the documentation for more details:      https://github.com/mashpie/i18n-node
    __n: function(){
        return i18n.__n.apply(this, arguments);
    },
    //Custom helper to reuse urls
    url: function(name){
    //We only need to access to the JSON previously loaded, and   return the value of the key we receive as a parameter
        return urls[name];
    },
  }
}index.handlebars<!DOCTYPE html>
<html>
<head>
 ..
</head>
<body>..
 <! — This way we use our helper for languages →
 <h3>{{i18n “welcomeText”}}</h3> <! — Note: Every key will be automatically added to the json of each language after a page that uses this key is visited, and only in that languages dictionary →
 <! — This will generate a key:value pair with the same value as the key, so we need to change them after we visit them for the first time →<! — And this way we could use some maintable links →
 <a href=”{{ url ‘home’ }}”>{{i18n “home”}}</a> <! — Note2: The URLS are not automatically added, so we need to add them before visiting the page →
 
 ..</body>
</html>

After the first visit, and after changing the values for the i18n JSONs the page should render the texts in the language requested if it is in the available ones. And now it should be easier to update texts or urls that appear multiple times on your site just by updating them once.

http://www.erikiado.com
https://github.com/mashpie/i18n-node
https://github.com/ericf/express-handlebars

Express i18n with handlebars and maintainable links

Written by Erik Ibarra