Locale Support in Qt 5

This article may require cleanup to meet the Qt Wiki's quality standards. Reason: Auto-imported from ExpressionEngine. Please improve this article if you can. Remove the {{cleanup}} tag and add this page to Updated pages list after it's clean.

QLocale in Qt 5

Early Qt localization support was weak with a design based on Windows APIs, but with its own code and data. Over time new features have been introduced based on CLDR data, but the current QLocale implementation is still incomplete, inconsistent, not fully integrated with the host system locale, and unnecessarily bloats the core library. It is clear that Qt needs a new approach.

Current Support

Qt provides two core options for localization:

• System Locale: Use the default system locale settings, the implementation being platform specific.
• Custom Locale: An application can replace the default system locale with any custom locale supported by the CLDR data embedded in QtCore which is then used by Qt's internal code routines.

On Windows, Mac and Blackberry the System Locale uses the localization data of the host system, falling back to embedded CLDR data where the host system doesn't provide the required data, and using a mixture of of the host parse/format code and Qt's own code.

On all other platforms such as Linux and Android the embedded CLDR data is used instead.

A number of key requirements for future improvements were defined:

• Minimise locale data shipped with Qt
• Minimise localization code needing to be maintained by Qt
• Add support for time zones
• Add support for calendar systems
• Add support for localized collation
• Add support for advanced formatting/parsing options
• Integrate fully with the system locale on all platforms

A number of options have been investigated for implementing these improvements.

The initial plan was to extend the existing QLocale code and data with new code, code from KDE, and more data from CLDR As a test case calendar system support was added using KDE code and CLDR data, but this proved to be unacceptable in terms of the library size required by the new data. It would also result in a lot of new code that Qt would struggle to code and support, especially in difficult areas like collation.

The second plan was to utilise ICU as the localization back-end on all platforms to minimise code and data requirements within Qt. This had the advantage of a single code base and consistent behaviour and feature set across platforms. The main disadvantage was that ICU does not respect a users personal preference overrides or the host settings, so would be inconsistent. This option proved unworkable however due to resistance from Windows devs to the extra dependency and download, Apple App Store policies preventing linking to ICU, and Android only shipping the Java version.

The third plan adopted is to implement individual system back-ends for each host platform to fully utilise the system locale resources. While considerably more code, and limited to a lowest common denominator feature set, it will at least provide a fully integrated appearance. This is the option now documented below.

Detailed planning for the ICU option can be found at Qt-5-ICU. Many of these details will still apply to the new host-based plan.

Platform Support

While we cannot use ICU directly on all platforms, all platforms except Win32 either use ICU or CLDR and so have a consistent feature set, object model and api that we can design to. The exception of Win32 will restrict those features that we can expose in QtBase, but we may be able to offer a QtAddon that supports the advanced features. The lowest common denominator version of ICU appears to be a very old ICU 4.0 due to OS X 10.6 support, but the lowest version common to the reference platforms (OS X 10.7, Ubuntu 11.10) and Android is ICU 4.4 which will be the minimum feature set supported.

As at Qt5.4 the minimum supported platforms are:

Platform	Reference	Official	Community
Windows	7	XP*, Vista
Windows Embedded			CE 7.0
Windows Phone	8.1
Windows RT	8.1
Mac OSX	10.8	10.7	10.6?
Mac iOS	8	8.1	5.0?
Linux Ubuntu	11.10	11.10	10.4
Linux RHEL	6.5	6.5
Linux OpenSuse	13.1	13.1
Android	4.4	???	2.3.3?
QNX	N/A	6.6.0

ICU

ICU ships standard on all modern Linux and BSD distros, and is shipped standard with QNX. With POSIX locale functions being clearly deficient (i.e. no calendar system support, poor collation, etc) then this is the preferred back-end for use on all Unix-like platforms, including embedded and QNX.

Ubuntu 10.04 ships ICU xxx while Ubuntu 11.10 LTS ships ICU 4.4. QNX xxx ships ICU version xxx.

Mac OS X / iOS

Mac uses ICU for localization, but does not ship the ICU headers and prohibits apps that link to ICU from the App Store. Instead we must use the native Mac API which in reality is a thin wrapper around ICU with a simplified API and some Mac convenience methods added.

Qt 5.2 supports a minimum of OS X 10.6 which ships ICU 4.0 (see http://opensource.apple.com/), OS X 10.7 ships ICU 4.6

Android

Android uses ICU for localization, but only ships the Java version of the library. We will use the Java Android api via JNI.

Qt 5.2 Android support requires Android API level 9 (Honeycomb) which ships with ICU 4.4 (see http://developer.android.com/reference/java/util/Locale.html). Android 3.0 also ships 4.4, and Android 4.00 ICU 4.6.

WinRT

WinRT does not document what version of ICU or CLDR it uses, but it is clear that it does so. An initial review of the Windows api indicates are required features are exposed.

Win32

Win32 is the main problem platform.

Embedded / Fallback

Some embedded platforms may prefer not to ship ICU, or may only have very simple localization requirements. It may be possible to provide a fall-back implementation for these platforms. This could be the existing QLocale code and database, but that would be a substantial maintenance burden. The alternative is to ship a simple C-locale back-end.

Components

QTimeZone

QTimeZone has been successfully implemented in Qt 5.2 using separate back-ends for each system but a common API. The design of this class will be copied for much of the new QLocale implementation, especially QCalendar.

In 5.3 a number of new features are still required, including a QEvent for TimeZoneChanged and a QTimeZoneDatabase class to load TZ databases on any platform.

Old design details can be found at http://wiki.qt.io/Qt-5-QTimeZone

QCalendar

QCalendar will follow the design of QTimeZone to wrap the system provided calendar calculators.

Not all platforms equally support the same set of calendar systems, although this is slowly converging thanks to the increasing use of CLDR and ICU. While QCalendar will have to define an enum for all possible calendar systems, it will also have to provide an availableCalendarSystems() api to describe what systems are available to be set in the formatter.

QCalendar will implement baseline support for as many calendars as possible so that even where a calendar system is not available on a host system it may still be used as an optional calculation class, but not in the formatter.

ICU C++: http://icu-project.org/apiref/icu4c/classicu_1_1Calendar.html

• ICU C: http://icu-project.org/apiref/icu4c/ucal_8h.html
• Android / ICU4J: http://developer.android.com/reference/java/util/Calendar.html
• Mac Cocoa: https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSCalendar_Class/Reference/NSCalendar.html
• WinRT: http://msdn.microsoft.com/en-US/library/windows/apps/windows.globalization.calendar.aspx
• Win32: http://msdn.microsoft.com/en-us/library/windows/desktop/dd319114(v=vs.85).aspx