Installing The Aurelia-I18N Plugin in a CLI App

The new hotness with Aurelia is the brand new CLI Tool. It helps you to create a new project easily by just asking you a few questions and on you go. Since I saw this request few times, here is a short intro in how to install the Aurelia-I18N plugin in your newly created CLI Application.

First you want to install the plugin via npm:

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"
}

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

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

In there add subfolders for each language you’d like to support, eg 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.

/**********************************************/
/          add the necessary imports           /
/**********************************************/
import environment from './environment';
import Backend from 'i18next-xhr-backend';

//Configure Bluebird Promises.
//Note: You may want to use environment-specific configuration.
Promise.config({
  warnings: {
    wForgottenReturn: false
  }
});

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .feature('resources');

  if (environment.debug) {
    aurelia.use.developmentLogging();
  }

  if (environment.testing) {
    aurelia.use.plugin('aurelia-testing');
  }

  /**********************************************/
  /             register the plugin              /
  /**********************************************/
  aurelia.use.plugin('aurelia-i18n', (instance) => {
    // register backend plugin
    instance.i18next.use(Backend);

    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.

As always, I’m happy about reading your comments below

photo credit: Gerd Altmann: Kontinente Flaggen Silhouetten via Pixabay (license)