Internationalize and Localize your Ionic 2 Application

In this post, we will explain how to implement multiple language support for your Ionic 2 app using the ng2-translate library and Cordova Globalization plugin. In short, in this tutorial:

  • We will use Supermodular 2 starter app and set it all up and running.
  • We will use Cordova Globalization plugin in order to make the app recognise the user’s device language settings.
  • We will use the ng2-translate library to load the appropriate language and allow the user to change the language of a screen from within the app.
  • Finally, we will configure the side menu so our new screen is included.

Note: The complete source code of this tutorial is available in the ionic2-i18n Github repository.

Download code

Prerequisites

Supermodular 2 is a free starter template that allows you to start a new Ionic 2 project quickly offering some basic features commonly used in recent mobile applications. We are going to use it in order to build a basic Ionic 2 app with an extremely modular architecture and best software development practices applied.

Step 1: Clone GitHub Repo

Visit http://github.com/appseed-io/supermodular2 and download or clone the Supermodular 2 app:

$git clone https://github.com/appseed-io/supermodular2.git

Alternatively, it is recommended that you fork the repository since, later, you will be able to push any code you will add to this project straight to your own project repository.

Step 2: Install libraries

Open a terminal window and navigate to the supermodular2 folder. Install the NodeJS dependencies:

$npm install

Step 3: Install plugins and platforms

Install all the required Cordova plugins the app needs with the following command:

$ionic state restore

This command will actually restore all the platforms and plugins are included in the package.json file.

Note: In case you do not work on a Mac OS machine, open the package.json file and replace the iOS platform with the Android platform or leave the cordovaPlatforms array empty if you do not want to add a platform yet.

Step 4: Run the app

In your terminal, make sure you are located in the supermodular2 folder and run the command:

$ionic serve --lab

Also, you can run the app in a simulator. For example, in order to run the app in an iOS emulator execute the command:

$ionic emulate ios

Step 5: Scaffolding the I18N module

Let’s start by building the basic structure of the new module following the modular architecture of the Supermodular 2 app. Firstly, open the app.module.ts file under the src/app/ path where all the app modules are collected and import our new I18nDemoModule as highlighted below:

Then, create an i18n-demo folder where all the code related to this module will be included. Place this folder under the src/pages/ path. So, the first thing is to create the I18nDemoModule module we imported previously. For the time being, this module will not do anything really but we will enrich it later. Therefore, in the i18n-demo folder, create the i18n-demo.module.ts file and paste the following code:

As we have already imported i18nDemoPage in the I18nDemoModule module, it is time to create the i18n-demo.page.ts file with the following code that simply links it to the related HTML template:

The HTML template is going to be pretty empty for now. Just create the i18n-demo.html file and paste the code in there:

To end with the scaffolding, we are going to add a menu entry so we can access the new screen from the side menu. In order to do that, open the app.component.ts file and add the highlighted lines of code:

Step 6: Run/Test

By now, we should be able to run our app and see the newly added screen:

Step 7: Installing necessary libraries and plugins

To make the translations happen, we will use the ng2-translate library, the internationalization (i18n) library for Angular 2. It can be installed by executing the command:

$npm install ng2-translate --save

Also, we will use the Cordova Globalization plugin to obtain the user’s device language. So, we are going to install it by running:

$cordova plugin add cordova-plugin-globalization

Do not forget to include cordova-plugin-globalization in your package.json file too, so it can be installed with the rest of the plugins anytime you install your project from scratch. To do that, open the package.json file and add cordova-plugin-globalization in the cordovaPlugins array.

Step 8: Initializing the Angular Translate Library

In order to use ng2-translate, we must import it in the NgModule of the application.

The TranslateLoader loads the JSON files that contain the translated strings of the app. So, let’s import this in the app.module.ts file too.

Since by default, it will look for translation JSON files in the i18n/ folder, for Ionic 2, we must change this to src/assets/i18n. For this reason, we are going to create a custom TranslateLoader:

Notice that the Angular Translate library requires the Angular Http module. So, we must import this too.

Consequently, the TranslateModule.forRoot() will use the custom TranslateLoader as follows:

As a result, the app.module.ts file will include the following code:

Step 9: Using the Angular Translate Library

Our new screen should load the text that corresponds to the user’s device language and also, it should provide the option for the user to choose a language from a list and change the language of the text shown on the screen.

We will collect all the variables we want accessible throughout the whole new feature in the i18n-demo.constants.ts file. These are actually constants that we want to protect from being re-declared or changed through re-assignment. The constants we are going to need are the available languages in which we have translated text, the default language that will be used in case we do have translated text and the system language where we will store the selected language by either the user or the device language settings.

For our example, the available languages will be english and russian and the default language will be english. Thus, the i18n-demo.constants.ts file will look similar to the following piece of code:

Setting the user language on screen load

We will take into consideration two different cases in order to decide which language the app will load; the case of running the app on an actual device and the case of running the app on the browser.

Since the requirement is to get the user’s language and display the related translated text on the screen load, we will add the following code in the i18n-demo.module.ts file as highlighted:

Let’s take a closer look at the code. The case, of running the app on an actual device, is detected by checking if the cordova object is existent in the global scope. In this case, we get the device language by calling the getPreferredLanguage() function provided by theGlobalization plugin. Then, we check if the device language exists in the available languages we translated the text into and finally it uses it for the translation. In case there is no translation available for the device language, then the screen is translated into the default language we set earlier.

Similarly, when the app runs on the browser, we use the getBrowserLang() method provided by the Angular Translate library to return the current browser language and we follow the same logic. Also, note how we imported the TranslateModule, so we can use it in the I18nDemoModule.

Allowing user to set the language in app

It is time to create the HTML template where we are going to display the translated text and the list of the available languages the user will choose from. Therefore, open the i18n-demo.html file and replace the content of the screen we scaffolded earlier with the following code:

We will explain later how to pass translated strings into the template, but, for the time being, we will focus on how to make the list of the available languages accessible to the user. We basically use ion-radio Ionic buttons to bind the user option to the model as a selectedLanguage and ionChange from the Ionic API that will emit the applyLanguage() method for the selectedLanguage.

To implement this method and provide the data for this screen, open the i18n-demo.page.ts file and add the highlighted code:

Step 10: Creating Translation Files

The simplest way of providing the translation values for a language is assigning each string to a translation key and creating a JSON file containing all the keys of the strings that need to be translated and the related translated text. Since we set the path to our JSON files to /src/assets/i18n/, create an i18n folder under the /src/assets/ path and create the en.json file for the all the text in english and the ru.json file for the text in russian.

Thus, all the highlighted keys in our template will be included in the en.json file that will have the following structure:

Similarly, the ru.json file will be:

However, sometimes we want to pass translation values from the Page to our template. Still using the pipe, we pass the value as a parameter that is defined in the I18nDemoPage. Importing TranslateService in I18nDemoPage, let us pass translation values to the template.

As a final step we place the value in curly brackets in the JSON file:

Additionally, we can use TranslateDirective to get the translation values following the pattern below:

Notice how the “INNER_CONTENT” key is provided a little different than the previous cases.

Final Result

Running the app on an iOS/Android emulator, you should be able to see the new screen with the available languages listed.

You can choose the russian language from the list or the device settings and see the text translated in russian.

Conclusion

In this tutorial, you learnt everything you need to know on how to build an Ionic 2 app in order to make it available in multiple languages and gain more users. After all this preparation, there is no need to worry in case you need to translate your app even in a hundred languages. Now, you are ready to grow your apps even more!

Found this tutorial interesting?

To find internationalisation and many more features to incorporate in any Ionic 2 mobile app, check out Barebone Ionic 2, the Swiss Army Knife of Ionic2!

Interesting in Ionic?

Check out our Ionic and Ionic 2 Starter Kits and Application Templates.

References

Ionic2, Angular2, Source code of this tutorial, cover photo.

Stay tuned

Join our list and sing up to get early access to our latest news and free tutorials about Ionic.