Localising applications

This section describes how to create a MeeGo 1.2 Harmattan application that is easily adaptable for multiple target countries and regions by means of internationalisation and localisation. Internationalisation refers to the act of creating such an application, whereas localisation is the act of adapting it to a particular region.

To localise your application, you may need to:

Enable your application to use translated text.
Enable your application to adapt to local conventions, for example, by presenting the date, time, numbers, and currency in different formats.

The user experience documentation briefly discusses localisation in general and use of text specifically.

Qt supports the creation of easily localisable internationalised applications. You can use Qt Creator to render text that contains characters from a range of different writing systems. For more information, see Internationalization with Qt.

You can also take a look at the Qt Quick example provided by Qt. However, to create an internationalised application, you must go beyond the QML code.

Note: For information on how to localise the long and short descriptions and the name displayed for Harmattan applications, see Packaging your application.

Example application

This simple example application shows how to internationalise a template application and localise it to a few additional languages. The application uses an appropriate string to greet the user, based on the device settings. The application is localised to American English, British English, and Finnish.

Prerequisites

You have installed the Qt SDK with the Harmattan target on your host workstation.
You have configured the device-to-SDK connection and device access in Qt Creator.
You have English and Finnish in the set of supported languages. To verify which languages are available, go to Settings > Time and Language > Language. If English and Finnish are not available, use other languages.

Creating the application

To create the example application:

1. Install Qt Linguist, unless you have already done so. To install the tool, click Help on the Qt Creator top toolbar and select Start Updater. On the Package manager tab, you can find the Qt Linguist from under Qt SDK > Development Tools > Qt Linguist.

2. Create a project using the Qt Quick Application template:

a. Name the application 'localhello'.

b. Select Qt Quick Components for MeeGo/Harmattan as the application type.

c. Select Harmattan as target.

d. Do not change the default icon.

e. Verify that Make application boostable is selected.

f. Add the packaging files created by Qt Creator to your project.

3. In the application's MainPage.qml file, change the Hello world! string to __Hello__ and remove the button to make the application more simple:

import QtQuick 1.1
import com.nokia.meego 1.0

Page {
    tools: commonTools

    Label {
        id: label
        anchors.centerIn: parent
        text: qsTr("__Hello__")
        visible: true
    }
}

4. Start a command-line interpreter and go to the project's qml directory.

5. To create a new directory called i18n for the internationalisation files, enter the following command:

mkdir i18n

6. To create a translation file for British English, enter the following command:

lupdate MainPage.qml -ts i18n/tr_en.ts

The translation file is now available in the i18n directory (it is used as a fallback if the en_GB localisation file is not available).

7. Create translation files for the localised versions for US English (en_US) and Finnish (fi), as well as any others you are using. Enter the following commands:

lupdate MainPage.qml -ts i18n/tr_en_US.ts

lupdate MainPage.qml -ts i18n/tr_fi.ts

8. Start Qt Linguist and load all the translation files.

9. Change the strings. The following figure illustrates how the localised versions are shown in Qt Linguist.

Localised strings in Qt Linguist

10. To finalise the translation, approve the changes by clicking on the tick mark buttons and save.

11. To generate the runtime translation files for all the localised versions, enter the following command:

lrelease i18n/*.ts

12. Check that the translation files are now available in the i18n directory.

13. Create a Qt resource compiler file (.qrc) file and add all the translation files to the file.

14. Select File > New File or Project > Qt > Qt Resource File.

15. Name the file res.qrc and add it to the project.

16. Add the / prefix to the .qrc file.

17. Add the .qm files to the .qrc file.

18. Create aliases for the translation files. The following figure illustrates how translation files are shown in Qt Creator when British English, American English, Finnish, Australian English and Chinese translations are available.

Translation files in Qt Creator

19. To load the translation files, change the main.cpp file as follows:

#include <QtGui/QApplication>
#include "qmlapplicationviewer.h"

Q_DECL_EXPORT int main(int argc, char *argv[])
{
    QScopedPointer<QApplication> app(createApplication(argc, argv));
    QScopedPointer<QmlApplicationViewer> viewer(QmlApplicationViewer::create());

    QString locale = QLocale::system().name();
    QTranslator translator;

    // fall back to using English translation, if one specific to the current
    // setting of the device is not available. 
    if (!(translator.load("tr_"+locale, ":/")))
        translator.load("tr_en", ":/");

    app->installTranslator(&translator);

    viewer->setOrientation(QmlApplicationViewer::ScreenOrientationAuto);
    viewer->setMainQmlFile(QLatin1String("qml/localhello/main.qml"));
    viewer->showExpanded();

    return app->exec();
}

You can now test your localised application by running it on the device.

Running the application on the device

To run your application on the device:

1. Click the Target Selector

, and select Harmattan and the configuration you are using.

2. The application is built before it can be run on the device. Above the Target Selector, Qt Creator displays Evaluating, Parsing, and Scanning status bars. Wait until the processes are complete.

3. Click

Your application is installed on the device. After installation, the application runs on the device. The application displays "Hello" when the device uses the British English language setting.

4. Change the device language to Finnish and tap the localhello application icon in the Applications view. The application displays "Mo".

5. Change the device language to American English and tap the localhello application icon in the Applications view. The application displays "Yo!".

Notes

A list of supported languages is available in the libmeegotouch library in the Platform API reference.

You can use Qt Simulator to test the localisation by selecting the language manually (either in the initialisation code or through an in-application selector).

Additionally, the app variable is not a pointer in applications that are not boosted. Thus, you must refer to the installTranslator method in the main.cpp file directly, not through a pointer.

Further information

For more information on localising applications, see the following links:

Internationalization with Qt
QML Internationalization
Qt Linguist Manual
The Internationalization and localization wikipedia article
The libmeegotouch library in the Platform API reference