Internationalize and Localize your Ionic Application

By making use of Angular Translate, Angular Dynamic Locale and Cordova Globalization Plugin

Releasing an application in a single language can shrink its audience severely. Considering that, Internationalization can provide multiple language support to your application.

Introduction

Releasing an application in a single language can shrink its audience severely. Considering that, Internationalization can provide multiple language support to your application.

This tutorial will guide you through everything you need to know in order to internationalize and localize your Ionic application with the use of three really helpful technologies:

• Angular Translate
• Angular Dynamic Locale
• Cordova Globalisation plugin.

Download the code

Note: Stay up-to-date and learn how to internationalize an Ionic 2 app.

What Internationalization is

To begin with, it is very common the misunderstanding between the terms Internationalization and Localization. Obviously, they have a strong association with each other.

According to Angular:

Internationalization (i18n) is the process of developing products in such a way that they can be localized for languages and cultures easily. Localization (l10n), is the process of adapting applications and text to enable their usability in a particular cultural or linguistic market.

In other words, Internationalization is a pre-stage of localization as it prepares your app in terms of designing and building for its localization. Basically, this implies the abstraction of the strings and all the locale/culture-sensitive bits of the application.

Prerequisites

Ionic uses AngularJS for a lot of the core functionality of the framework. As a result, this tutorial assumes that you use AngularJS for your app.

For the scaffolding of our Ionic app we will use Yeoman AngularJS generator. Yeoman generator is popular for creating Ionic hybrid mobile applications using AngularJS and Cordova and lets you quickly set up a project with sensible defaults and best practices.

Install Yeoman

Make sure that yeoman is installed in your development box. This is an one-line command using npm:

$ npm install -g yo

More information http://yeoman.io/

Step 1: Create a new basic Ionic application

In this section, we will create a basic Ionic application. This will be the application we will extend by adding i18n support. With yeoman, npm and bower already installed in your machine you are ready to generate the basic application that will be used in this tutorial.

First, create a folder for your application, which, in our case, will be named “i18n-ionic-tutorial”

$ mkdir i18n-ionic-tutorial && cd $_

Run the yeoman generator by passing the app name:

$ yo ionic i18n-ionic-tutorial

Use your favorite editor and open the content of the “i18n-ionic-tutorial” folder. In our case we are using Atom. Sublime is also a very good choice. Any code editor will work though.

Step 2: Installation and configure the modules

We will use the AngularJS module angular-translate which will make the whole handling of language translation really easy for us. Also, for setting/changing angular locale, namely formatting date, time, currency, Angular Dynamic Locale library will be used.

But how the app knows which language the device is set for? For that, Cordova Globalization plugin needs to be downloaded and installed. We will use this plugin since it provides a variety of useful internationalization tools, such as getPreferredLanguage function, which will find the preferred language according to the device settings.

angular-translate

Firstly, we are going to load the angular-translate library. We can do this using Bower. We will add the related package in the list of dependencies in the bower.json file which allows the install and update of this package and any other packages specified in this file with a single command. The related lines in the bower.json file will be the following:

Next, we need to declare angular-translate as a module load dependency in the app.js file:

Angular Dynamic Locale

Similarly, we need to load the Angular Dynamic Locale library. Again, we will do this using Bower. Thus, in the bower.json file, we will add the related package in the list of packages. The related line in the bower.json file will be the following:

As we did with Angular Translate previously, we will declare Angular Dynamic Locale as a module load dependency in the app.js file:

app.js

Cordova Globalization Plugin

Since Cordova Globalization plugin is part of the ngCordova arsenal, we need to inject this dependency in the app.js file:

app.js

Cordova Globalization plugin needs to be added either with the command:

$ cordova plugin add cordova-plugin-globalization

or, in case that you use npm, you need to include it in your package.json file. We prefer the second way, thus, we will add the following line in the package.json file:

package.json

For further reading, check out Apache’s documentation.

Now, execute the following command and the new-inserted plugin will be installed:

$ npm install

Also, run the following command and the new-inserted packages will be installed:

$ bower install

Step 3: Creating the translation files

In order to create the language translation files, we are going to use translation keys in the project’s view templates, for example in app/templates/tab-dash.html:

tab-dash.html

Note that, after the translation key, the translate filter follows which translates the contents of the respective translation key.

Then, you need to create the translation JSON file with the actual translated text which corresponds to the related translation keys. For this tutorial, we named the folder containing the translation files i18n and the JSON translation file is en-US.json:

en-US.json

File naming convention

The name of the files, with the translation strings, should be in the xx-YY.json form where xx-YY stands for the “Language code and Subcode” or “Tag”.

The translation codes-subcodes you used for the translation files naming will be used for the specification of the language angular-translate requires in order to “speak” a language.

And here comes the question “What translation codes can I use?”. The best practices regarding the codes-subcodes creation are illustrated in W3C’s Internalization guidelines.

Note that, in W3C’s Internalization guidelines, codes are referred to as tags. Following the standard W3C recommends, the language codes are the same for all programming languages and they suggest a common interpretation by all professionals as most locale-aware applications conform to this standard. Some code examples following this standard are “en-US” and “ru-RU”. Though, you can use any language codes you prefer.

Step 4: Creating the locale files

Angular supports many different locales that can be downloaded from the related repository.

Later on, we will make Angular Dynamic Locale aware of where all the locale files are located.

For this tutorial, we named the folder which they are contained in locales under the app/ folder as follows:

angular-locale_en-us.js

Step 5: Prepare the App and load the initial Language/Locale

Configuration

Set the available languages

Now, it’s time to declare all the available languages for Angular Translate to make use of. Here, we will use the language codes we referred to previously. We will do this by adding the following line of code in the app.js file:

app.js

Also, in order to provide the location, in the filesystem, from where the app will load the locale files for Angular Dynamic Locale, we need to configure them using tmhDynamicLocaleProvider.

All of the configuration of the translation and locale files takes place in the following lines:

app.js

At this stage our application is ready and translated in english. But, we will go one step further and, in the next section, we will make our app able to take into consideration the language settings of the device in order to decide which language the text will be translated into.

Step 6: Detect and set the the language/locale on run

First, we need to call a setLanguage() method in the ready() function which will change the app’s language while the app is still running according to the User’s device settings:

app.js

Here, we see the setLanguage() method. It makes use of the device’s preferred language and then it finds the suitable language that is going to be used for the translation:

app.js

getSuitableLanguage() will return the language among the available languages we declared previously:

app.js

Finally, the applyLanguage() method will set the language with the help of Angular Dynamic Locale:

app.js

Step 7: Adding a language

Once you have done all the work to design and build the core of your app, you can add as many languages as you prefer. For example, we will add french in three steps:

a. We will create the fr-fr.json file with the translated text under app/i18n path:

fr-fr.json

b. We will download the angular-locale_fr-fr.js file from Angular’s repo and place it under the app/locales path:

angular-locale_fr-fr.js

c. Declare it in the available languages in app.js:

app.js

Run the app

We can either run the app on the browser with the command:

$ grunt serve

or on a smartphone simulator. For example, for iOS, we firstly need to add the platform:

$ grunt platform:add:ios

and, then run the app on a simulator:

$ grunt emulate:ios — livereload

Conclusion

In this tutorial, we learnt how to build and design an Ionic app in order to make it internationalized in 7 steps. After all this preparation, there is no need to worry in case that you need to translate your app even in a hundred languages. Now, you are on your way to internationalizing your Ionic applications!

Found this tutorial interesting?

You can find a full demonstration of an Ionic App Internationalization that takes account the locale set by the User and adjusts app’s content accordingly or, if not set, adjusts app’s content according to the default language.

A production ready Ionic i18n Application which demonstrates and extends everything that is described in this tutorial is available in CodeCanyon.

The source code of the example used in this tutorial is available in GitHub.

1. I18N Ionic — Full Application
2. I18N Ionic Tutorial

Follow us on Twitter, or Google+ or even check our CodeCanyon Profile. You may also take a look at our website www.appseed.io

Interesting in Ionic?

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

References

Ionic, AngularJS, Yeoman, Yeoman AngularJS generator, Source code of this tutorial, See-ming Lee for the cover photo.

Happy coding,
The AppSeed team

/Stavros Kounis, skounis.github.io