i18n Internationalisation for your Progressive Web Apps

Today I gonna tell you how to easily use the i18n feature of QCObjects to have internationalisation and multi-language content into your components.

Latest version of QCObjects

First, make sure you got the latest version of QCObjects, you can install it either using npm or by using a one-step installation script, or if you only want to use the Jamstack front-end side, you can consume it from a popular CDN like jsdelivr or cdnjs (soon, by now it's stuck in the queue...).

More info about installing QCObjects here

SDK Required

Are you using this setting?

CONFIG.set('useSDK', true);

Good! Keep going!

(Don't worry, since the latest version it is automatically set for you and if you didn't realised of this setting before, you have to do nothing )

Built-In Components i18n

Almost on every dynamic component created by QCObjects you have the ability to translate its contents automatically. To do that, you gonna use the i18n feature that is present on every component that has been loaded after the SDK.

Write the component contents in English!

You only need to write in English first, once you do that, you can automatically translate the contents using regular expression keywords and messages.

By example:

If you component contents are like this:

<!-- component template contents -->
<p>This is a paragraph</p>
<!-- end of component template contents -->

You don't need to change anything in your template in order to be able to translate it.

To enable the i18n feature, go to the place where you've put the initial CONFIG settings (maybe the init.js file ) and add the following line:

CONFIG.set('use_i18n', true);

Done, QCObjects is now trying to find some i18n package in your project to use as a language dictionary and translate every single component it can do on the fly every time it is rebuilt (yes, including the routing and re-routing processes).

Then, create a new package with a name like this: "org.quickcorp.i18n_messages.[LANG]" where [LANG] is the short name of the language you are using (by example: "es", "ru", "it"). I don't recommend you to use composed names of languages like "es-CL" or "us-CA" as it is not supported yet by the translator.

For Spanish, the right name of the package will be: org.quickcorp.i18n_messages.es

And the name of the file for the package will be:

org.quickcorp.i18n_messages.es.js (don't forget the JS extension here!)

NOTE: You don't have to Import this package! It's automatically imported by QCObjects for you, when it's detecting that your browser is using another language different from "en"!

The content for your new package it's up to you, but you have to follow this format (the example is for Spanish "es" language keyword):

'use strict';
// file: js/packages/org.quickcorp.i18n_messages.es.js
Package('org.quickcorp.i18n_messages.es', [
  Class('i18n_messages_es', i18n_messages, {
    messages: [
       // ... your custom language dictionary is here
    ]
  }),
  {
    _i18n_messages_es: New(i18n_messages_es) // this line is so important
  }
]);

Inside the part that was commented as "your custom language dictionary is here", you have to code your dictionary. Every element of the dictionary has to be like this:

{
   "en":"This is a paragraph",
   "es":"Esto es un párrafo"
}

So, the complete content of your package will be like this:

'use strict';
// file: js/packages/org.quickcorp.i18n_messages.es.js
Package('org.quickcorp.i18n_messages.es', [
  Class('i18n_messages_es', i18n_messages, {
    messages: [
       // ... your custom language dictionary is here
      {
         "en":"This is a paragraph",
         "es":"Esto es un párrafo"
      }
    ]
  }),
  {
    _i18n_messages_es: New(i18n_messages_es) // this line is so important
  }
]);

Do you need to add another term? OK, just add another element to the dictionary:

'use strict';
// file: js/packages/org.quickcorp.i18n_messages.es.js
Package('org.quickcorp.i18n_messages.es', [
  Class('i18n_messages_es', i18n_messages, {
    messages: [
       // ... your custom language dictionary is here
      {
         "en":"This is a paragraph",
         "es":"Esto es un párrafo"
      },
      {
         "en":"Welcome to my new app",
         "es":"Bienvenido a mi nueva app"
      }
    ]
  }),
  {
    _i18n_messages_es: New(i18n_messages_es) // this line is so important
  }
]);

And so on...

The complete example here:

<!-- file: templates/components/mycomponent.tpl.html -->
<!-- component template contents -->
<h1>Welcome to my new app</h1>
<p>This is a paragraph</p>
<!-- end component template contents -->
'use strict';
// file: js/packages/org.quickcorp.i18n_messages.es.js
Package('org.quickcorp.i18n_messages.es', [
  Class('i18n_messages_es', i18n_messages, {
    messages: [
       // ... your custom language dictionary is here
      {
         "en":"This is a paragraph",
         "es":"Esto es un párrafo"
      },
      {
         "en":"Welcome to my new app",
         "es":"Bienvenido a mi nueva app"
      }
    ]
  }),
  {
    _i18n_messages_es: New(i18n_messages_es) // this line is so important
  }
]);
<!-- file: main.html or wherever you inject this component -->
<component name="mycomponent"></component>
<!-- remember: the extension and path of the template will not be used here, "mycomponent" will be "templates/components/mycomponent.tpl.html" according to your CONFIG settings -->
// file: js/init.js
CONFIG.set('use_i18n', true);

Last comments

Just one last recommendation, please try to not overuse this feature, fulfilling your dictionary with repeated phrases without checking and re-checking your syntax, as it affecting the global performance when it has to translate so many repeated terms. And just one last thing, this is not "Google Translator", it is only a way to make it easy to build a multi-language app that is loaded progressive and not affecting your component structure.

Enjoy coding!