Internationalize Mobile Apps

Introduction

This internationalization guide explains how to give your end-user an easy way to change their mobile application’s language. The user can do so directly on their Android or iOS device.

This guide shows one of the ways to change the language on a native app. You can also apply this guide’s mechanism to all offline PWA profiles. Please note that this guide’s mechanism does not change the localization of an application because it depends on the settings of the device.

While this guide gives your end-user the ability to switch their app’s language, translation is a different issue. Translating native apps and PWAs actually works the same as it does for web apps. To learn more about app translation, see Translating Your App Content.

Prerequisites

Before starting this guide, make sure you have completed the following prerequisites:

• Install Mendix Studio Pro 9.14.0 or above

• Complete the Prerequisites section of Build a Mendix Native App in the Cloud

• Make sure your Nanoflow Commons module is up to date

• Read the Language Menu guide to understand the basics of the Mendix Language menu

• Set up the required languages in Studio Pro—this tutorial has been configured with three languages as below:

  

Setting up the Language Change Mechanism

Internationalization with Mendix’s mobile apps is fairly simple. You will use two nanoflow actions to set up most of your language change mechanism.

Adding the Module and Microflow

You can either add a new module to your existing app, or create a new Studio Pro app using a Blank Native Mobile App template and then adding a new module to it. Either way, your setup will begin with the same step and continue on accordingly:

1. Add a new module ChangeLanguage to your app.
2. Add a new microflow ACT_Language_ChangeUserLangRuntime to your ChangeLanguage module and configure it as such:

   1. Add a parameter called LanguageCode of data type String.

   2. Retrieve the language that was selected by the user on the app:

      1. This can be done by using a Retrieve object activity.

      2. Select the source as Database and entity System.Language.

      3. As you need only one language, select range as First and pass the XPath constraint as [Code=$LanguageCode].

      4. Name this retrieved object SelectedLanguage.

      5. Your microflow should look like this:

         

   3. To set the selected language, you need to change the language for the current user:

      1. Call a Change object activity.

      2. Select the Input as currentUser (System.User).

      3. In the Action section, Commit should be set to Yes and Refresh to client set to No.

      4. For Member, select System.User_Language.

      5. For the value of that member, set it as the object retrieved earlier: $SelectedLanguage.

      6. Your microflow should look like this:

         

Your microflow ACT_Language_ChangeUserLangRuntime is now ready to be called from a nanoflow which you will configure in the following section.

Adding the Nanoflow

Add a new nanoflow ACT_Language_ChangeUserLangDevice to your module and configure it like this:

1. Add a parameter called SelectedLanguage of data type Object and entity System.Language. This parameter will be the new app language as selected by the user.

2. Make a microflow call to ACT_Language_ChangeUserLangRuntime, the microflow you made previously.

3. In that microflow call, click Edit parameter value, select Expression, and write $SelectedLanguage/Code as the expression. This microflow call now sets the language as selected by the user.

4. Now the cached session needs to be cleared from local storage. Simply call a nanoflow action Clear cached session data.

5. To load the new language, you must refresh the app. This can be done by calling a nanoflow action Reload.

6. Your nanoflow should look like this:

   

Adding the Native Page

Add a new native page Language_Overview to your ChangeLanguage module, then do the following:

1. Add a title called Select language, as the selected language in Studio Pro is English. You can use a Text widget, but anything with a string value is fine.
2. Then underneath the title, add a native List View by simply dragging from the toolbox to list all the available languages on the app. Configure it this way:
   1. In the Data source tab, Type should be Database, Entity should be System.Language.
   2. In the General tab, On click should be configured to call a nanoflow ACT_Language_ChangeUserLangDevice.
   3. Click on the OK button.
      • You should get a dialog box asking Do you want to automatically fill the contents of the list view? Select Yes.
   4. List View should be populated with two fields: {Code} and {Description}. Delete the {Code} field.
3. Ensure the caption of the {Description} field in ListView is not empty. It should be mapped to the attribute System.Language.Description with the {1} variable and be used as well.
4. Change to the second language in Studio Pro by going to menu Language > Current Language > <second_language>.
5. Add a translation of the title in a second language if not available.
6. Ensure again that the caption of the {Description} field in ListView is not empty. It should be mapped to the attribute System.Language.Description and be used as well.
7. Repeat the above steps to add a translation for the third language as well.
8. Set Language_Overview as the default home page of the Native mobile navigation profile:
   1. Open Navigation in the App Explorer.
   2. Click the Native mobile tab.
   3. Set Language_Overview as the default home page.

Testing Language Switching

Now it is time to see the app in action. If you are using a PWA, you can simply test in a web browser.

To test your native app, locally deploy and view the app on the Make It Native 9 app:

1. Follow the steps in Downloading and Installing the Make It Native App to view your app in Mendix’s Make It Native testing app.

2. Once the app is running, you should be able to see the native Language_Overview page:

   

3. To change the language, do the following:

   1. Tap Dutch, Netherlands.

   2. The app should be reloaded automatically.

   3. You should be able to see the title in the Dutch language:

      

Congratulations, you just implemented internationalization in your native app! Your users will appreciate the power of multiple languages at their fingertips. For more information about languages and Mendix, see the Read More section below.

Read More

• Using Translatable Validation Messages
• Language Menu: gives more information on translating the languages of different Mendix UI elements
• Change Language by Clicking a Link: explanations and ideas in the Mendix Community for refreshing the page when the language is changed
• Anonymous User Journey: a discussion in the Mendix Community about switching languages for anonymous end-users