- 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.
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
$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:
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
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
Step 8: Initializing the Angular Translate Library
In order to use ng2-translate, we must import it in the NgModule of the application.
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
Notice that the Angular Translate library requires the Angular
Http module. So, we must import this too.
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
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
ionChange from the Ionic API that will emit the
applyLanguage() method for the
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, 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.
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.
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!