Globalize your app

Qt provides tools and a methodology for internationalizing your app. For full details, see Internationalization and Localization with Qt Quick.

The general steps are as follows:

1. Ensure internationalization is taken into consideration in your QML files, including the use of text strings, disambiguating identical text, and the use of parameters and locales.
2. Use the cmd line tool lupdate.exe to generate the base translation file, and copy the base translation file and name it for each required language.
3. Use Qt Linguist to open these files and provide the translations.
4. In Qt Linguist, choose File > Release or use the cmd line tool lrelease.exe to generate the translation files.
5. Include these translation files in the project that will be made into a stand-alone app.

Internationalize your QML

The Qt Company recommends completing the following steps to internationalize your QML:

1. Use qsTr() for all literal user interface strings.
2. Add context. Use comment lines to describe where a string is used, using specific syntax. //: is a comment for the translator, while //~ is optional extra information.
3. Disambiguate identical texts. If a term can have multiple meanings, add a second parameter to differentiate, for example, text: qsTr("back", "not front"); text: qsTr("back", "go backward").
4. Use %x to insert parameters into a string, for example, text: qsTr("File %1 of %2").arg(counter).arg(total) .
5. Use %Lx so numbers are localized, for example, text: qsTr("%L1").arg(total) .
6. Internationalize dates, times, and currencies, for example, text: qsTr("Date %1").arg(Date().toLocaleString(Qt.locale())) .
7. Use QT_TR_NOOP() for translatable data text strings.
8. Use locale to extend localization features where possible.

For details on each step, see Internationalization and Localization with Qt Quick.

You should also consider internationalization when you include images in your app. The image that you display may differ depending on the selected language. The following example shows how to detect if a right-to-left (RTL) language is in use, and sets a user-defined property named mirror . This property is then used to determine which image will be displayed.

1
2
3
4
5
6
    property var localeForRTL:["ar", "he", "he-IL"]
    property bool mirror: localeForRTL.indexOf(Qt.locale().uiLanguages[0]) > -1

    Image{
        source: mirror ? "./RTLimage.png" : "./Image.png"
    }

lupdate

lupdate is a Qt command line tool located in the AppStudio installation folder.

To run, open a cmd window in your project directory and run the following command. Keep in mind that the period used in each of the following examples represents the current directory, which is the app folder containing .qml files.

On Windows:

C:\Users\UserName\ArcGIS\AppStudio\Apps\MyApp>"C:\Users\Username\Applications\ArcGIS\AppStudio\bin\lupdate.exe" . -extensions qml -ts languages/MyApp_en.ts

On macOS:

/Users/UserName/applications/ArcGIS/AppStudio/tools/lupdate . -extensions qml -ts languages/MyApp_en.ts

On Ubuntu:

~/Applications/ArcGIS/AppStudio/bin/lupdate . -extensions qml -ts languages/MyApp_en.ts

A new file will be created named MyApp_en.ts.

Translations for new languages are created by copying and renaming the file MyApp_en.ts once for each language required, and substituting the en with the language code for each required language. The .ts files can then be edited with Qt Linguist.

For additional details, see Using lupdate.

Qt Linguist

Linguist is a GUI tool located in the AppStudio installation folder. You open the .ts files that were created with lupdate in Linguist and add the translations for each of the strings listed. Only strings marked as done will be processed by the lrelease tool.

For additional details, see the Qt Linguist Manual.

lrelease

You can generate the release files in the following ways:

• Open the completed .ts file in Linguist, and from the File menu, choose Release. A .qm file will be created to correspond with your .ts file.

• Use the cmd line tool. lrelease is a Qt command tool located in the AppStudio installation folder. The runtime translation files can be generated by running the following command, listing each language file to be generated:

  lrelease.exe languages\MyApp_ar.ts languages\MyApp_fr.ts

• Pass the -help option to lrelease to view supported options.

For more information, see Using lrelease.

Deploy localization files with your app

Before using the Make tool to create installation files, ensure that you include your .qm files in your project. A recommended folder naming convention follows:

MyApp > languages > qml_localecode.qm

For example, if your app contains localization for German, French, and Chinese, you would include the following files:

• MyApp > languages > qml_de.qm
• MyApp > languages > qml_fr.qm
• MyApp > languages > qml_zh.qm

You also must tell your app where to find these files. This information is defined in the appinfo.json file. Open appinfo.json in a text editor, and add the following property:

1
2
3
4
    "translations": {
        "fileName": "qml",
        "path": "languages"
    },

In the example above, the file name is qml . You do not need to include the underscore and language code. The folder name in the code sample is languages , which also matches the example above. You can choose your own folder and file names; just be sure to nominate these in the appinfo.json file.

When you run your app on a device with a system locale that matches a language you've supplied a translation file for, the app will automatically display strings from the correct file. An alternative for testing purposes is the command line parameter --locale , which will override the system locale with whatever locale code you have included in the parameter. For example, appending --locale fr to the command line will launch the app using French localization files. These command line parameters can also be used when running your app in AppStudio, by setting the parameter in the Command line arguments: field in the Qt Creator Projects tab.

When using an app with translation files provided and set up, different translation files can be loaded within the app by using the loadTranslator method in the AppFramework component.

Localize your store listing

If you choose to distribute your app via a store, and if you have made the effort to globalize your app, you should also consider localizing your store listing. Both the App Store and Google Play offer the ability to localize your store listing. In both cases, you have the opportunity to provide localized descriptions and screen captures for each store language into your single app submission.

For more information, see the following:

• Localize App Store information for AppleApp Store
• Translate and localize your app for Google Play