Handling locale-dependent data

Make sure the application is able to format language- and region-dependent elements correctly (for example, dates, times and currencies).

To produce code that takes the locale into account, it is recommended that you use the components provided by the platform to handle language- and country-specific data formats. Qt's QLocale class provides functions for formatting locale-related data.

The Symbian locale model separates locale settings into language, region, and collation settings. For example, for the Chinese market, a device using English language-related locale data could use Chinese region data (for example, currency and measurement units), and Chinese collation for comparing and sorting strings.

If your application only retrieves the locale data, you only need to listen to the QEvent::LocaleChange() event from the standard Qt event system, and update the UI with new locale data.

Locale data change is not handled seamlessly in Qt/QML. In order to react to Symbian locale changes, some coding on Qt side is needed. When Locale data is changed (for example, user changes time separator character in Time and Date Settings), Qt will send a QEvent::LocaleChange() event. Simply listening for this event and updating the data in QML is enough.

bool appInstance::event(QEvent *event) {
    if(event->type() == QEvent::LocaleChange) {
        updateQMLData

There are two basic approaches on how to update the UI/data on QML side. One can either get the data from C++ to QML by utilising Q_INVOKABLE, or set the data from C++ to QML by using setContextProperty. In the code example, the latter approach is chosen. The reasoning supporting this approach is that QML will stay declarative, no need to code anything on QML side.

In application cpp:

view.rootContext()->setContextProperty("timeNow", QDateTime::currentDateTime().toString(Qt::SystemLocaleShortDate));

And in QML:

Text {
        text:  qsTr("time separator: %1").arg(timeNow)
    }

Note that time and date separators are the only few things which can be currently changed by user. Other QLocale data changes are generated otherwise.

To test the example code, just unzip it and open the .pro file with Qt Creator. To test on Windows XP, run the application, go to Control Panel, choose Regional and Language Options. Under Regional Options tab, choose an item from topmost pull down menu (NOT the "location"). Hit Apply. See the changes in the application.

To test on device, get device connected to the PC so that you can run QML applications from Qt Creator. You may have to install Qt 4.7.1 or later and TRK to the device. When the application is running on the device, go to settings->phone->time and date->Date Separator. Change that to something else than the current. Go back to the application and verify the changes.

Here is a good document how C++ and QML can talk to each other: Qt binding.

User-modifiable locale settings

In Symbian devices, users can modify the following locale settings:

  • Time format and separator character

  • Date format and separator character. Out of the four separators that are defined, users can only change the two middle ones.

  • Digits (Arabic, Urdu, Farsi, and Hindi only). In the Arabic UI, the user can select whether the default digits are European or Arabic-Indic digits (numerals).

If the user changes the device language, the changes made for the previous language are saved, and will be restored when the user switches back to that language. For example, if the user often switches between two languages that use a different date format, the user can define a different date format to be used for each device language. The device may also modify some locale-related settings automatically, for example, update the date from the network due to a daylight savings change, or if the user moves to a different time zone.

Locale support available in Qt

The Qt platform provide functions for formatting the following language- and region-dependent elements:

Functionality

Classes to use

Dates and times

QLocale provides detailed functions for handling specific parts of date and time expressions, such as the number of components used in the expressions, or the separators used between the components.

Numbers

QLocale provides functions for formatting number expressions, such as the decimal separator used.

Currencies

QLocale provides detailed functions for handling specific parts of currency expressions, such as the currency symbol used, or how negative currencies are formatted.

Measurement units

QLocale provides functions for handling measurement expressions, such as whether the metric or imperial measurement system is used. This can be defined separately for short and long distances.

Locale-dependent handling not available in Qt

Qt classes do not support handling of the following locale-dependent data:

  • Addresses may vary, for example, in the number of address fields used and in which order they are given. Make sure that there are no mandatory fields (for example, state). Examples of formatting addresses:

    • United States: <first name> <last name> <house number> <street> <city> <state abbreviation> <zip code> <country>

    • Finland: <first name> <last name> <street> <house number> <postal code> <city> <country>

    • Russia: <country> <postal code> [region] <city> <street> <house number> <apartment number> <last name> <first name> <paternal name>

  • The digits in phone numbers may be grouped differently depending on the locale, and the separator used may vary. In Symbian, number grouping for phone numbers is only available for the US English variant. An example of formatting phone numbers is 555-1212.

  • Names of measurement units, for example, kB

  • Paper sizes, for example, DIN A, US letter and legal sizes, and Japanese sizes

  • List separator, for example, a comma or semicolon

  • Order of the first name and last name. For example, in Hungarian, Chinese, and Japanese, the last name is displayed before the first name.

To enable the localization of this data, do not hard code it. You can provide the localized data in the .ts translations files. Alternatively, you can enable users to set the data. For user-changeable settings, there must be a localizable default.