Internationalization

Internationalization is the process of developing an application so that it can be adapted to various languages and regions without any code changes. This means translation of text, re-arranging controls and converting text to different layouts and formats. The internationalization APIs in the BlackBerry 10 OS provide several benefits, including support for many locales, consistent formats, and it reduces maintenance and translation costs. Cascades now provides you with support for complex text languages. It integrates the text layout engine within its framework which handles the display of languages like Arabic, Thai, Hindi, and so on.

Internationalization support in Qt

Qt provides most internationalization APIs to perform correct localization. You must use the relevant Qt classes and APIs which support internationalization before text can be translated by Cascades. One of the most important components of these Qt APIs is the QLocale class, which contains the bulk of the methods for internationalization. Qt 4.8 contains information on formatting (numbers, currency, date and time, quotes, and lists), date and time, and measurement systems (metric or imperial). To learn more, see the Qt reference documentation about internationalization.

Although Qt provides a healthy set of APIs for you to perform localization, the BlackBerry 10 OS supplements these Qt APIs where they lack functionality. See Internationalization support in Cascades to learn more.

Number formatting

You can use the following Qt methods to print or parse numbers in different formats.

QLocale::toString(int n)
QLocale::toUInt(QString s)
QLocale::toDouble(QString s)

Here's an example that shows how to use the Qt number formatting API for a given locale. In this example, a random number is formatted using English-US, French, Hindi, Thai, and Arabic locales.

QLocale US(QLocale::English, QLocale::UnitedStates);
QLocale FRANCE(QLocale::French, QLocale::France);
QLocale INDIA(QLocale::Hindi, QLocale::India);
QLocale THAILAND(QLocale::Thai, QLocale::Thailand);
QLocale SAUDI(QLocale::Arabic, QLocale::SaudiArabia);
 
QList<QLocale> locales;
locales << US << FRANCE << INDIA << THAILAND << SAUDI;
 
QString text = qApp->translate("MyNumberFormatAppContext",
"Qt Number Format Example\n\n");

double randomNumber = -123456789.340;
foreach(QLocale currLocale , locales)

{
    text += QLocale::countryToString(currLocale.country())+ "\n" +
    qApp->translate("MyNumberFormatAppContext","Random Number: ") 
    + currLocale.toString(randomNumber,'f',3) + "\n\n";
  }

Here's the output:

Number format sample
Locale: French

Random Number: 12875
Decimal Point: ,
Negative Sign: -
Positive Sign +
Zero Digit: 0

Currency formatting

The following Qt method can be used for the localized representation of a currency value:

QLocale::toCurrencyString(qlonglong value, const QString & symbol = QString())

Here's an example that shows various currency formatting in English-US, Chinese, and Hindi locales.

QLocale US(QLocale::English, QLocale::UnitedStates);
QLocale CHINA(QLocale::Chinese, QLocale::China);
 
QList<QLocale> locales;
locales << US << CHINA;
 
float randomPrice = 14.99;
QString text = qApp->translate("MyCurrencyAppContext",
"Qt Currency Support Example\n\n");

foreach(QLocale currentLocale , locales){
    text +=  "\n" + QLocale::countryToString(currentLocale.country())+ "\n";
    foreach (QLocale currencyLocale, locales)
{
    //We recommend you use the standardized QLocale::CurrencyIsoCode 
    //instead of QLocale::CurrencySymbol. i.e. 14.99 USD vs $14.99
    text +=  currentLocale.toCurrencyString(randomPrice,
    currencyLocale.currencySymbol(QLocale::CurrencyIsoCode)) + "\n";
    }
}

Here's the output:

Qt currency support example

UnitedStates
USD14.99
CNY14.99

China
USD14.99
CNY14.99

Date and time formatting

The following Qt methods represent date and times in different locales:

QDate QLocale::toDate(const QString & string, FormatType format = LongFormat)

QTime QLocale::toTime(const QString & string, FormatType format = LongFormat)

QDateTime QLocale::toDateTime(const QString & string, 
    FormatType format = LongFormat)

QString QLocale::toString(const QDate & date, const QString & format)

QString QLocale::toString(const QDateTime & dateTime, 
    FormatType format = LongFormat)

Quotes

The following Qt method supports quoting strings based on the specified locale:

QString QLocale::quoteString(const QString & str, QuotationStyle style = 
    StandardQuotation) and its overloaded variant.

Lists

The following Qt method provides support for constructing a list of strings separated by a locale-based separator:

QString QLocale::createSeparatedList(const QStringList & list)

Calendar support

The following Qt methods provide support for formatting the day, week, and month for the specified locale. Only the Gregorian calendar is used in the calendar support.

QLocale::weekdays()
QLocale::firstDayOfWeek()
QLocale::dayName(int day, FormatType type = LongFormat)
QLocale::monthName(int month, FormatType type = LongFormat)

Measurement system

The following Qt methods provide support for handling measurement units (metric or imperial) of a specified locale:

QLocale::measurementSystem()

Internationalization support in Cascades

The BlackBerry 10 OS supplements the Qt 4.8 internationalization APIs with some libraries of its own. These libraries are called bbsystem and bbutilityi18n. These libraries can be added to your project by adding the following line in your main.pro file:
LIBS += -lbbsystem -lbbutilityi18n

The BlackBerry 10 OS provides you with the ability to separate regional formatting settings for a specified locale and the UI settings for a specified locale. This is useful in cases when a user wants to change their local calendar but the UI translations for that locale are not available. Another use is when a user prefers to see the UI in English but wants to use the metric system and the Euro currency option in the regional settings. This functionality is offered by Cascades in the form of an accessor method and a Qt signal, both of which require a locale type defined by bb::system::LocaleType::Type enum.

bb::system::LocaleType::Messages

Allows the application to retrieve the user's UI locale preference.

bb::system::LocaleType::Region

Allows the application to retrieve the formatting locale that best reflects their present location.

Formatting

Qt's QLocale offers mostly ShortFormat and LongFormat formatting types. The BlackBerry 10 OS further extends these formatting types to: date, time and percentage. The following methods return the localized format:

bb::utility::i18n::dateFormat(DateFormat::Type)
bb::utility::i18n::timeFormat(DateFormat::Type)
bb::utility::i18n::dateTimeFormat(DateFormat::Type)

The type of date format can be: short, medium, long, and full. Also, the overloads of the functions above accept QLocale as a first parameter. Here's some sample code that prints out ICU styled data and time formats in English-US, French, Arabic and Hindi locales.

QDateTime currTime = QDateTime::currentDateTime();
 
    QLocale US(QLocale::English, QLocale::UnitedStates);
    QLocale FRANCE(QLocale::French, QLocale::France);
    QLocale SAUDI(QLocale::Arabic, QLocale::SaudiArabia);
    QLocale INDIA(QLocale::Hindi, QLocale::India);
    QList<QLocale>locales;
    locales << US << FRANCE << SAUDI << INDIA;
 
    
QString RLM = QString::fromUtf8("\u200F");
text += qApp->translate("MyFormatAppContext" , 
    "\n\n DateTime Format Example \n\n");
 
foreach(QLocale currLocale , locales){
text += QLocale::countryToString(currLocale.country())+ "\n";
text += qApp->translate("MyFormatAppContext","SHORT: ") + RLM;
text += currLocale.toString( currTime, bb::utility::i18n::dateTimeFormat
    ( currLocale, bb::utility::i18n::DateFormat::Short ) ) + "\n";
text += qApp->translate("MyFormatAppContext","MEDIUM: ") + RLM;
text += currLocale.toString( currTime, bb::utility::i18n::dateTimeFormat
    ( currLocale, bb::utility::i18n::DateFormat::Medium ) ) + "\n";
text += qApp->translate("MyFormatAppContext","LONG: ") + RLM;
text += currLocale.toString( currTime, bb::utility::i18n::dateTimeFormat
    ( currLocale, bb::utility::i18n::DateFormat::Long ) ) + "\n";
text += qApp->translate("MyFormatAppContext","FULL: " ) + RLM;
text += currLocale.toString( currTime, bb::utility::i18n::dateTimeFormat
    ( currLocale, bb::utility::i18n::DateFormat::Full ) ) + "\n\n";}
}

Here's the output:

Screen showing the output from the code example.

Collation support

The BlackBerry 10 OS uses QtCollator, which is part of Qt 5.0, as a basic string sorting and comparison engine in Cascades. Here are some important QtCollator methods:

int compare(QString &s1, QString &s2)

Allows localized comparison between two strings.

QtCollator(QLocale &locale = QLocale())

Allows you to specify the locale in the constructor.

void setLocale(const QLocale &locale)

Allows you to set a locale.

void setStrength(Strength)

Performs case-insensitive comparisons.

For more information, see ICU Collator documentation.

Related resources

Design guidelines

 
 

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus