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.
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:
Cordova Globalization Plugin
Since Cordova Globalization plugin is part of the ngCordova arsenal, we need to inject this dependency in the app.js file:
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:
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:
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:
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:
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:
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:
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:
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:
getSuitableLanguage() will return the language among the available languages we declared previously:
Finally, the applyLanguage() method will set the language with the help of Angular Dynamic Locale:
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:
b. We will download the angular-locale_fr-fr.js file from Angular’s repo and place it under the app/locales path:
c. Declare it in the available languages in 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.
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