Aurelia i18n Update and CLI Tutorial

Posted by AureliaEffect on August 22, 2016

Today, Core Team Member Vildan Softic gives us an update on Aurelia's i18n library and explains how to configure it for an Aurelia CLI project as well as TypeScript. Take it away Vildan...

Aurelia-CLI is alive and kicking. Lot's of you have already jumped onboard and enjoy the easy way to get started with Aurelia. It helps you to create a new project easily by just asking you a few questions and on you go. Since I (Vildan) have seen this request a few times, here is a short intro on how to install the aurelia-i18n plugin into your newly created CLI Application.

Installing aurelia-i18n

First you want to install the plugin via npm, from within the root folder of your project:

    npm install aurelia-i18n

Since aurelia-i18n is backed by i18next, you should install it and a backend plugin of your choice. As an example we're going to leverage the i18next-xhr-backend:

    npm install i18next i18next-xhr-backend

After that we need to tell our CLI App about the new dependencies. To do so we're going to open the file aurelia_project/aurelia.json and scroll down to section named dependencies. In there add the following three entries:

      "name": "i18next",
      "path": "../node_modules/i18next/dist/umd",
      "main": "i18next"
      "name": "aurelia-i18n",
      "path": "../node_modules/aurelia-i18n/dist/amd",
      "main": "aurelia-i18n"
      "name": "i18next-xhr-backend",
      "path": "../node_modules/i18next-xhr-backend/dist/umd",
      "main": "i18nextXHRBackend"

Note: A future version of the CLI will automate this last step by introducing a new command, au import, which will attempt to auto-configure the libraries for you.

Setting up your Project

Great! Now, following the official Aurelia-I18N Guide , we create a folder in the root of your app named locales.

Note: You have to put the folder into the root (on same level as src) as this is the hosted root of your app.

Within this folder, add subfolders for each language you'd like to support. e.g. en and de for English and German language.

Inside of each of those folders create a file named translation.json with your translation keys and values. Follow the official guide for detailed info.

Last but not least, it's time to wire up the plugin inside your app. Therefore go to your src/main.js file and configure it as follows (don't forget to add the imports).

    //add the imports
    import environment from './environment';
    import Backend from 'i18next-xhr-backend';
    //Configure Bluebird Promises.
    //Note: You may want to use environment-specific configuration.
      warnings: {
        wForgottenReturn: false
    export function configure(aurelia) {
      if (environment.debug) {
      if (environment.testing) {
      //register the plugin
      aurelia.use.plugin('aurelia-i18n', (instance) => {
        // register backend plugin
        return instance.setup({
          backend: {                                  
            loadPath: './locales/{{lng}}/{{ns}}.json', 
          lng : 'de',
          attributes : ['t','i18n'],
          fallbackLng : 'en',
          debug : false
      aurelia.start().then(() => aurelia.setRoot());

Now you should be all set to start using the features of aurelia-i18n inside your app.

Bundling the Intl Polyfill

aurelia-i18n uses a polyfill to provide Intl.API support for browsers currently not implementing the feature. Amongst those are Safari for Mac and iOS. The Polyfill will be lazy loaded in dev mode as needed but won't be included automatically as part of the bundle. The reason is the file size of ~50k in minified mode. As such, you as the developer have to opt-in and bundle the Polyfill manually (if you don't want it lazy loaded).

To do so, first install the Polyfill as part of your project using npm:

    npm install intl

After that, open up the aurelia_project/aurelia.json file and add the following dependency:

      "name": "intl",
      "path": "../node_modules/intl/dist",
      "main": "Intl.min"

Note: Instead of using a main of Intl.min you could also reference Intl.complete to include the Unicode CLDR locale data. For more info about this option consult the official Polyfill docs .

I18N and TypeScript

Clearly a major goal of the CLI is to also easily provide support for TypeScript-based apps. For quite some time, the TypeScript issue with the I18N plugin wasn't related to the plugin itself, but to the way the dependencies offer their definition files. In order to get started with a TS app, first follow all the steps as described in the Setting up your Project section.

Next install the already preconfigured typings by executing:

    typings install

Additionally add the i18next.d.ts by calling:

    typings install dt~i18next --save --global

Note: I18Next is hosted on DefinitlyTyped, as such you need to use the --global modifier to target typings to said source. This modfier used to be named --ambient.

The next thing that is missing is the i18next-xhr-backend.d.ts file. Since this file is neither available from the typings registry nor DefinitlyTyped, you should install it using a local link.

    typings install --save --global file:./node_modules/i18next-xhr-backend/typings/i18next-xhr-backend.d.ts

The last thing left is to handle an issue with the way TS resolves the default exported class. As such, you need to change the import statement of the Backend in your main.ts file to:

    import environment from './environment';
    import * as Backend from 'i18next-xhr-backend';  <--- see this changed line in order to make TS compiler shut up

After that you should be ready to use aurelia-i18n with your TypeScript-based CLI-App.


If you have followed the progress of the aurelia-i18n library you have seen that a lot of issues have been fixed and closed, new features such as the missing NfBindingBehavior and DfBindingBehavior have been added, as well as support for custom elements and much more.

We'd like to encourage everyone to give aurelia-i18n a try and support your visitor's experience with a seamless international appearance. Last but not least, we'd also like to see what you've built using aurelia-i18n. A great opportunity to showcase your app is the Built With Aurelia site mentioned in a previous post . For further details on today's aurelia-i18n release update, we provide the release notes below.

Release Notes

aurelia-i18n 1.1.0 (2016-08-22)

Bug Fixes

  • eslint: fix linting issues ( 0ddf93d )
  • ts: declare missing props ( c8102c8 )


  • i18n: add dependency injection ( 0545999 )
  • TCustomAttribute: support custom-elements ( 06373f0 )