Translating Your App Content

Last modified: August 20, 2024

Introduction

Delivering your Mendix app in multiple languages is an important capability for reaching a wide audience. Most of the text that the end-user sees is stored as translatable texts (for example, labels, button names, and menu items). Using the language features of Mendix, you can quickly make your app multilingual and translate the content to many other languages.

This how-to teaches you how to do the following:

Add a new language to your app
Change the working language
Translate individual items of text
Translate multiple items of text in one operation
Change multiple items of text in one operation
Copy a translation from one language to another

It is assumed that you know the basics of creating new apps and editing them.

Creating a Sample App

To demonstrate working with languages, you will create a new app from the blank app template. You will add some text to this app, as an example, but the app you create is to demonstrate the language features of Mendix and is not intended to be run.

When you create an app from a Mendix template, there is one language available: English, United States. You usually set this to be the Default language. This is the language that is displayed when an end-user has no language selected, or when your app does not support their selected language.

To create your app, do the following:

Create a new app using the Blank App template. If given the option, leave the Default language as English, United States.
Open the app in Studio Pro.
Create a domain model in MyFirstModule with two entities:
- Order with the Integer attribute OrderNumber
- Product with the String attribute ProductName
Right-click one of the entities and select Generate overview pages.
In the Generate pages dialog box, ensure both entities are selected and click OK.

This generates some pages containing text for you to translate.
Open the page Product_NewEdit and add a new Button widget.
Change the text on the new button to Order. You will use this button to allow the end-user to order the product they are viewing. Ignore the warnings about the setup of this button.
Open the page Home_Web and add some text into the title and subtitle.

You now have an app with some translatable texts.

Adding App Languages

You can now add an additional language to your app.

If you want to create the whole app in a language other than the current default, it is best to do this before you start creating the app. If you want to add alternative languages, it is best to do this when your app is nearing completion, as it reduces the amount of work needed to do the translation from the default language, especially if there is already a translation for that language.

To add an additional language, do the following:

Select the menu item Language > Language Settings to open the App Settings dialog box.
Click Add to open the Add Language dialog box.
Select a Language. In this example, we select Chinese (Simplified), China, but you can use any language you like.

Mendix recommends that you do not choose Dutch, Netherlands, as this already contains translations for many of the translatable texts.
Click OK to save the changes.

In the App Settings window, the default language is still English, United States. This is the language that the end-user sees if they do not choose Chinese as their language.
Click OK.

Changing the Current Language

The current language is the language of the dictionary where any text you enter is stored. At the lower-right corner of the Studio Pro window, the language indicator shows which language is the current language.

To change your current language to Chinese, do the following:

Click the language indicator at the lower-right corner of the Studio Pro window.
Select Chinese (Simplified), China to make that your current language.

If you do more development later on, remember to change back to your default language so that any new text is recorded there and not in a translated dictionary.

Translating an Individual Piece of Text

Now that your current language is Chinese, you can translate some of the texts into that language.

Open the Home_Web page in Studio Pro.

The untranslated texts appear in the default language (English, United States) between angle brackets <>.
Enter your translation for the two text items on the page.

You have now added a translation for these two pieces of text.

Using Batch Translate

You can translate each piece of text individually. However, there are texts which appear multiple times (for example, Cancel, Delete, and Edit).

Mendix offers you a way to add a translation for all occurrences of a text at once.

Translating Multiple Texts

To translate multiple occurrences and multiple texts from the default language, English, to Chinese in a single operation, do the following:

Select the menu option Language > Batch Translate.
Select English, United States (default) as the Source language and Chinese (Simplified), China as the Destination language.
Click OK.
The Documents/modules field is set to (all). You initially want to work just on your module, rather than everything. To change this, click Select next to Documents/modules.
Make sure only the module MyFirstModule is selected. This restricts batch translation to this module.
Click OK. You can now see all the translatable texts in your module. The Translation (Chinese (Simplified), China) column shows the individual translations you made in the previous section. The # column shows the number of times each text appears in the selected module (or modules).
Enter translations in the Translation (Chinese (Simplified), China) column for the terms Cancel and Edit Order.
Click Translate to save the current translations.
Click Close to close the dialog box.
Open the Product_NewEdit page. The related terms now have Chinese translations.

Dealing With More Complex Translations

Sometimes a single word in the source language does not have a single translation in the destination language.

To handle this, follow the steps below:

Follow steps 1 through 6 in the previous section to see the list of texts in your module which can be translated from English, United States to (Chinese (Simplified), China.
In the Search field, enter Order.
In the grid, there are two lines for the text Order. The # column shows that there are three places where this text is used (one instance in the first line, and two in the second). The locations are listed in the Show occurrence field.
In the Show occurrence field, the Object column shows that one of the locations of the text Order is the Action button ‘actionButton3’ on the Product_NewEdit page. This is the button added to allow the end-user to order the product. To confirm this, double-click the row of Action button ‘actionButton3’.

In the background, the Product_NewEdit page opens with the button Order selected. This shows that this text is used on the button.
If you made any translations, click Translate to save them.
Click Close to close the dialog box.
In your app, the text Order is used as the command to order a product, and is used to refer to the Order entity. However, in Chinese, the translations for these two scenarios are different. To solve this issue, open the Product_NewEdit page.
Edit the text on the button to reflect the verb to order. In Chinese, this is 下单.
Go to the Language > Batch Translate to open the dialog box and search for Order in the module MyFirstModule.

Now in the grid, Order has two rows: one row has the translation 下单, and the other row has no translation.
In the row where Order has no translation, enter 订单. This is the Chinese translation for an order.
Click Translate to save the translation.
Click Close to close the dialog box.

You can now check that the correct translation has been applied to the other instances of Order (for example, on the Order_Overview page).

Replacing Text in Current Language

Once you have made some translations, you may want to look at the translations to check for spelling or consistency. To do this, use Batch Replace as follows:

Ensure your current language is the language you want to review. Batch replace works only on the currently selected language.
Select the menu item Language > Batch Replace.

The Documents/modules field is set to (all), so the dialog box shows all the translations in the current language dictionary. You can click Select next to this field and select only one module to reduce the scope. You can also search for a specific word in the Search field. The # column shows the locations where the text is used. These locations are listed in the Show occurrence section.
Enter any translations that need to be replaced in the Replace with column, then click Replace.

Copying to a New Language

Having translated your app, you may want to translate it into another related language (for example Dutch, Netherlands into Dutch, Belgium, English, United States into English, United Kingdom, or Chinese (Simplified), China into Chinese (Simplified), Singapore). Many of the translations will be the same, so you do not want to type them again.

To copy our Chinese (Simplified), China translations into a Chinese (Simplified), Singapore dictionary, do the following:

Go to Language > Language Settings.
Click Add to add Chinese (Simplified), Singapore as an app language.
Click OK to save the changes and close the App Settings dialog box.
Go to Language > Language Operations.
Select MyFirstModule. In the Chinese (Simplified), China column, it shows 8. This means there are 8 translations in the Chinese (Simplified), China dictionary.
Select Copy for the Operation.
Select Chinese (Simplified), China as the Source language.
Select Chinese (Simplified), Singapore as the Destination language.
Click Apply. Now in the Chinese (Simplified), Singapore column, it shows 8, too. Your Chinese (Simplified), China texts are copied to the Chinese (Simplified), Singapore dictionary. You can go to Language > Batch Replace to review them or go to Language > Batch Translate to change any cases where the Chinese (Simplified), China and Chinese (Simplified), Singapore translations are different.
Click Close to close the dialog box.

Other Considerations

Now that you know how to make translations of translatable texts, there are a couple of other things you may wish to investigate.

Completeness

To ensure all your text is properly translate, do a completeness check for your languages.

To set up the completeness check, do the following:

Go to Language > Language Settings.
In the grid, double-click the language for which you want to set the completeness check.
In the Check field, select the Check completeness checkbox.
Click OK to close the Edit Language dialog box.
In the App Settings dialog box, click OK to save the changes and close the dialog box. You then receive warnings about all text which has not been translated into that language. There is always a completeness check for the default language.

For more information, see Advanced Language Settings in the Language Settings reference guide.

You have seen how to create translations easily and copy your new translation to a new language in the current app.

What if you have several apps and want to add Chinese to all of them? Maybe you want to translate your own modules from scratch, but do not want to translate the system module, administration module, and Atlas UI all over again, as they do not change and you already have correct translations for these.

Mendix allows you to export a translation to an Excel file, either for the whole app or selected modules. You can then import this translation to another app and have your translation available to you.