How to Make a Multi Language App or Game with Felgo

More Resources for Internationalization

Additionally to this tutorial, you can also have a look at the following resources:

Overview

In this tutorial, you will learn how to prepare your app or game for multiple languages step by step. If you are new to Felgo, it may help to see the Felgo Games Tutorials before proceeding with this tutorial. You will use Qt Linguist for your translations which comes with the Qt SDK. Qt Linguist is automatically installed along with Felgo. You will find it as linguist.exe in the folder <Path to your Felgo SDK>\Felgo\[any-desktop-platform]\bin.

Localize your App or Game

First off, here is a short code example that shows how easy it is to localize Felgo apps or games:

 GameWindow {
   Scene {
     width: 480
     height: 320

     Column {
       anchors.centerIn: parent
       spacing: 6

       //create a localizable text with qsTr() and
       //make it dynamically change by binding to translation.language
       Text {
         anchors.horizontalCenter: parent.horizontalCenter
         text: qsTr("Hello World") + translation.language
       }

       //toggle language between german and english on button press
       GameButton {
         readonly property bool isEnglish: settings.language === "en_EN"

         anchors.horizontalCenter: parent.horizontalCenter

         text: "Switch to " + (isEnglish ? "German" : "English")
         onClicked: settings.language = isEnglish ? "de_DE" : "en_EN"
       }
     }
   }
 }

Use following directions to localize your app or game with Felgo in QML.

Prepare Texts

Wrap any string you want to translate in your QML files with the qsTr() function. If no translation is found during runtime, the text you provide within this function will be displayed directly. It is recommend to use English as default values.

 Button {
   text: qsTr("Hello")
 }

The qsTr() function also supports string arguments, plurals and more. For more information, see Localization with Qt Quick.

Translation Subfolder

To use translation files you need to create a subfolder similar to the translation folder in the ChickenOutbreak Demo. Create a subfolder in your project path called qml\translations similar to ChickenOutbreak ChickenOutbreak\qml\translations where the translation source files belong to.

Add Translation Files to your Project

Translation files can be automatically generated for all your qsTr function calls. In order for the generator tool to place them in the correct folders, add the following lines to your main .pro file:

 # this way, translations can be updated from inside QtCreator
 TRANSLATIONS = qml/translations/de_DE.ts \
                qml/translations/en_EN.ts

As you can see, there is one translation file for English and for German in this project. Similarly, you can add files for each language you want so support here. The first two letters of the language file are lowercase and express the target language. The last two letters express the target country. This is important when using different language files for the same language in different countries. For instance, the language German is de but there is a difference in German between Germany (DE) and Austria (AT). This means there are two different language files de_DE for German and de_AT for Austrian German.

Generate Translation Source Files

To generate the translation files, you run the lupdate tool from the Qt framework. There is a shortcut in QtCreator in the tools menu which will run the tool for you:

This will create the *.ts files you specified in your .pro file in the qml/translations folder.

Note: On windows, please make sure that the g++ path is part of your PATH environment variable. Otherwise, lupdate fails because g++ is not found.

Prepare Translation Files

Open all the *.ts files in Qt Linguist. When you open the new *.ts files you have to select the correct language settings for the source file. You can edit them anytime in Edit -> Translation File Settings. You should adjust them for every file.

Translate Texts

Translate the strings using Qt Linguist. For more information about Qt Linguist see the guide to using Qt Linguist.

Release Translation Binaries

When you have finished translating your app or game open the en_EN.ts file and release the strings as binary with File->Release as in the the qml translation folder qml\translations.

Alternatively, releasing the translations can be done be selecting lrelease from the Tools menu in QtCreator.

Now you will find a en_EN.qm file created in the qml\translations folder. The .qm files contain the compiled translations in binary. After you finished this step with all your language files you can run your app or game.

Note: The translations binaries require to be compiled along with your application. Translations are thus not available with Felgo Live, as no compilation step is involved for the live preview. To test your app with translations in Felgo Live, you can compile your own Live Client which then also includes your translations. The steps to do so are described in this guide: How to Build your own Live Client with Custom C++ and Native Code

Default Language

When starting the app or game, the language of the operating system is used as default language e.g.: de_DE on a german device. If this exact language is not available, any file with the same language but different country is used. If no translation file of the system language is available, Felgo will use English (en_EN) instead. Therefore, you should always provide an English version of your app or game. If en_EN.qm is also not available the texts will be displayed as you have stated them in your qml file.

The operating system language that is used when the app is started the first time is stored and will be overwritten only when the according GameWindowApplicationWindow::settings value is changed. It also won't change when the system language changes. If you want the application to start always with the currently active operating system language you can use the property translation.useSystemLanguage = true.

Language Change

You can change the language which is used during application startup by changing the according GameWindowApplicationWindow::settings value. The string provided here correlates to the name of the language files. The language of all your translated texts will be updated after an app restart.

 settings.language = "en_EN";

Dynamic Language Change

The application language can also be changed during runtime but this leads to extra work. Every string which should be translated needs to be extended with an additional binding to translation.language.

 Button {
   text: qsTr("Hello") + translation.language
 }

When you change the language during runtime as seen below the binding will reevaluate the string and the new language will be used.

 settings.language = "fr_FR";

Chicken Outbreak was translated into several languages for this tutorial which is also available with full source code when you download the Felgo engine in the <installation directory>/Demos/ChickenOutbreak directory. The online version is available here: ChickenOutbreak Demo.

Contents