KDE Core/KLocale/Frameworks

KDE Frameworks 5 Migration

This page summarises the steps required for the migration from KLocale to Qlocale in KDE Frameworks 5.

Split Locale and Translations

KLocale merges localisation and translation. In Qt these are separate. In Frameworks we will follow this model and split KLocale into 2. We will use QLocale everywhere for the localisation methods. We will use QTranslator / tr() in the tier 1 libraries where translation needs should be simple, but still hook this into the KDE translators workflow. In KDE applications we will use KLocalizedString (or a replacement) and i18n().

We can make a start on this now by replace many #include <klocale.h> references with <klocalizedstring.h> when i18n() is the only function required by a class.

Later KLocalizedString (or replacement) will need porting to use QLocale instead of KLocale.

Replace KDE Global Locale

KDE4 provides an app with its own KLocale instance which applies throughout the application instance and can be manipulated within that application instance. KGlobal::locale() returns the applications locale, which defaults to the KDE Locale unless overridden using KGlobal::setLocale() or the applications config file. This allows apps to seamlessly run with an alternative locale than the system locale and is a feature we need to retain.

Qt5 provides a System Locale and a Default Locale. Both are declared as global static variables in qlocale.ccp with file scope:

#ifndef QT_NO_SYSTEMLOCALE
QT_BEGIN_NAMESPACE
class QSystemLocale;
static QSystemLocale *QSystemLocale_globalSystemLocale();
QT_END_NAMESPACE
#endif

static const QLocalePrivate *default_lp = 0;
static uint default_number_options = 0;

The System Locale is what the system is currently set to and remains the same unless updated by the system, but the Default Locale can be changed by the application:

static void setDefault(const QLocale &locale);

void QLocale::setDefault(const QLocale &locale)
{
    default_lp = locale.d();
    default_number_options = locale.numberOptions();
}

This suggest the Qt Default Locale functions exactly the same as the KDE Global Locale in applying per application instance and will take the place of the KDE Global Locale.

To confirm:

• This does apply at application level
• This does apply to any Qt based libraries called by the application

The default QLocale() constructor returns the Qt Default Locale which is usually the System Locale unless changed using QLocale::setDefault(). QLocale::system() will always return the System Locale which may differ from the Default, so should be avoided unless explicitly required.

This implies that all code accessing KGlobal::locale().xxx() should simply be changed to be QLocale().yyy(). Due to the static privates the repeated construction should not be a performance issue, but apps can create a local var if needed, or we could request a QApplication::locale()?

Running with an envvar locale override will force Qt to override the system locale with the chosen locale under UNIX, behaviour under other platforms is unclear.

QLocale doesn't offer setXxx() api to allow apps to temporarily override a setting while running, and probably never will. Usually in KDE this is abused for things like temp changes to the date format when the normal format options api should be used, or a different locale object created.

For example:

KGlobal::locale()->setDateFormat("%y-%M-%d");
label = KGlobal::formatDate(myDate);

When it should be:

label = KGlobal::formatDate(myDate, "%y-%M-%d");

And under Qt5 will become:

label = QLocale().toString(myDate, "yyyy-MM-dd");

I doubt there are few if any valid use cases that can't be easily recoded. If the app wants say the date format to persist they can just save it in a local string and use that whenever they call the method.

Side-note: QLocale::setDefault() could be used in KDE4 Workspace with a custom QSystemLocale to force all Qt apps to use the KDE settings.

API Migration

While Qt 4.8 / Qt 5.0 provides most of the API needed, this are usually with very different method names, enums, and format codes. Some APi will not be available before Qt 5.1.

Migration is likely to be a very manual affair. A conversion table is provided below. Note method footprints are simplified for clarity.

Some interim migration tools may be required in a temporary class, such as ISO code conversions and splitLocale(), etc. The need for this can be assessed as we go.

This will be a lot of work for apps, so while frameworks switches to using QLocale directly, it may be desirable to provide a transition version of the KLocale api that uses QLocale as its backend and translates between the two.

For example, the app code:

label = KGlobal::locale()->formatDate(date, "%y-%M-%d);

could be replaced with:

label = K5Locale()->formatDate(date, "%y-%M-%d);

with K5Locale in turn translating the format string to the format required by QLocale::toString().

Locale

KLocale	Qt 5.0	Qt 5.1
KLocale(QString catalog, KSharedConfig::Ptr config)	Use QLocale() - Config no longer used - Set catalog in translation system
KLocale(QString catalog, QString language, QString country, KConfig *config)	QLocale(Language laanguage, Country country) - Config no longer used - Set catalog in translation system
void reparseConfiguration()	No longer used
static void splitLocale(QString locale, QString language, QString country, QString modifier, QString charset)	Not public, need to instantiate a locale and obtain that way.	Qt to be make public?

Countries

QLocale uses an enum value where KDE uses a QString ISO Code. Support may be added to Qt 5.1 to convert between the two, or this may be provided in the planned QtIsoCodes addon.

KLocale API	kdelibs usage	Qt 5.0	Qt 5.1
ISO codes as strings		enum Country	Conversion methods to be added
allCountriesList()	-	Not in Qt - loop from QLocale::AnyCountry to QLocale::LastCountry	Qt to add
QString country()	klocalizedstring.cpp	Country country() or name.split('_').at(1)	Provide ISO conversion methods
QString countryCodeToName(QString country)	Various	QString nativeCountryName() or QString countryToString(Country country)	Add nativeCountryName(Country country) ???
QString defaultCountry()	-	QLocale::C
bool setCountry(QString country, KConfig *config)	-	Create new instance QLocale(Language language, Country country)
QString countryDivisionCode () const	-
bool setCountryDivisionCode (const QString &countryDivision)	-

Languages

QLocale uses an enum value where KDE uses a QString ISO Code. Support may be added to Qt 5.1 to convert between the two, or this may be provided in the planned QtIsoCodes addon. Need some more thought with regard to localisation and translation split.

KLocale	kdelibs	Qt 5.0	Qt 5.1
ISO codes as strings		enum Language	Conversion methods to be added
QStringList allLanguagesList() const	kswitchlanguagedialog_p.cpp	None, loop from QLocale::AnyLanguage to QLocale::LastLanguage	To be added
QString language()	Various	Language language() or name.split('_').at(0)	Provide ISO conversion methods
QString languageCodeToName(QString language)	Various	nativeLanguageName() or English languageToString(Language language)	Add nativeLanguageName(Language language) ???
QStringList languageList()	Various	uiLanguages()
static QString defaultLanguage()	Various	QLocale::C
bool setLanguage(QStringList languages)	kswitchlanguagedialog_p.cpp		KDE Platform module
bool setLanguage(const QString &language, KConfig *config)	-	Create new QLocale(Language language, Country country)

Calendar / Date / Time

KLocale API	kdelibs usage	Qt 5.0	Qt 5.1
enum CalendarSystem
enum DateFormat
enum DateTimeComponent
enum DateTimeComponentFormat
enum DateTimeFormatOption
enum DateTimeFormatStandard
enum DateTimeParseMode
enum ReadDateFlags
enum ReadTimeFlags
enum TimeFormatOption
enum TimeProcessingOption
enum WeekNumberSystem
KCalendarSystem *calendar()
CalendarSystem calendarSystem()
QString calendarType() - Deprecated
QString dateFormat()
QString dateFormatShort()
bool dateMonthNamePossessive()
QString dayPeriodText(QTime &time, DateTimeComponentFormat format)
QString formatDate(QDate date, DateFormat format)
QString formatDateTime(QDateTime dateTime, DateFormat format, bool includeSecs)
QString formatDateTime(KDateTime dateTime, DateFormat format, DateTimeFormatOptions options)
QString formatDuration(unsigned long mSec)
QString formatLocaleTime(QTime pTime, TimeFormatOptions options)
QString formatTime (QTime pTime, bool includeSecs, bool isDuration)
QString prettyFormatDuration(unsigned long mSec)
QDate readDate(QString str, bool *ok)
QDate readDate(QString intstr, const QString fmt, bool *ok)
QDate readDate(const QString &str, ReadDateFlags flags, bool *ok=0) const
QTime readLocaleTime (const QString &str, bool *ok=0, TimeFormatOptions options=KLocale::TimeDefault, TimeProcessingOptions processing=ProcessNonStrict) const
QTime readTime (const QString &str, bool *ok=0) const
QTime readTime (const QString &str, ReadTimeFlags flags, bool *ok=0) const
void setCalendar (const QString &calendarType)
void setCalendarSystem (KLocale::CalendarSystem calendarSystem)
void setDateFormat (const QString &format)
void setDateFormatShort (const QString &format)
void setDateMonthNamePossessive (bool possessive)
void setTimeFormat (const QString &format)
void setWeekDayOfPray (int day)
void setWeekNumberSystem (KLocale::WeekNumberSystem weekNumberSystem)
void setWeekStartDay (int day)
void setWorkingWeekEndDay (int day)
void setWorkingWeekStartDay (int day)
bool use12Clock () const		Remove
int weekDayOfPray () const		Remove, try replace with weeend days instead
KLocale::WeekNumberSystem weekNumberSystem ()
KLocale::WeekNumberSystem weekNumberSystem () const
int weekStartDay () const
int workingWeekEndDay () const
int workingWeekStartDay () const
QString timeFormat () const

Numbers

int         decimalPlaces() const
QString     decimalSymbol() const
int         fracDigits() const
QString     negativeSign() const
QString     positiveSign() const
QString     thousandsSeparator() const

void        setDecimalPlaces(int digits)
void        setDecimalSymbol(const QString &symbol)
void        setFracDigits(int digits)
void        setNegativeSign(const QString &sign)
void        setPositiveSign(const QString &sign)
void        setThousandsSeparator(const QString &separator)

QString     formatLong(long num) const
QString     formatNumber(double num, int precision=-1) const
QString     formatNumber(const QString &numStr, bool round=true, int precision=-1) const

double      readNumber(const QString &numStr, bool *ok=0) const

Currency / Money

Basic functions supported in Qt 5.0, more in 5.1, advanced features of KCurrencyCode to be moved to new QtIsoCodes library.

KCurrencyCode *currency () const
QString        currencyCode () const
QStringList    currencyCodeList () const
QString        currencySymbol () const
int            monetaryDecimalPlaces () const
QString        monetaryDecimalSymbol () const
QString        monetaryThousandsSeparator () const
SignPosition   negativeMonetarySignPosition () const
bool           negativePrefixCurrencySymbol () const
SignPosition   positiveMonetarySignPosition () const
bool           positivePrefixCurrencySymbol () const
static QString  defaultCurrencyCode ()

void    setCurrencyCode (const QString &newCurrencyCode)
void    setCurrencySymbol (const QString &symbol)
void    setMonetaryDecimalPlaces (int digits)
void    setMonetaryDecimalSymbol (const QString &symbol)
void    setMonetaryThousandsSeparator (const QString &separator)
void    setNegativeMonetarySignPosition (SignPosition signpos)
void    setNegativePrefixCurrencySymbol (bool prefix)
void    setPositiveMonetarySignPosition (SignPosition signpos)
void    setPositivePrefixCurrencySymbol (bool prefix)

QString     formatMoney (double num, const QString &currency=QString(), int precision=-1) const

double  readMoney (const QString &numStr, bool *ok=0) const

Digit Sets

Not supported directly in Qt 5.0, some conversion happens implicitly, defer to 5.1 if really needed. In ICU fully supported implicitly.

QList<DigitSet> allDigitSetsList () const
DigitSet        digitSet () const
void            setDigitSet (DigitSet digitSet)
DigitSet        monetaryDigitSet () const
void            setMonetaryDigitSet (DigitSet digitSet)
DigitSet        dateTimeDigitSet () const
void            setDateTimeDigitSet (DigitSet digitSet)
QString         digitSetToName (DigitSet digitSet, bool withDigits=false) const
QString         convertDigits (const QString &str, DigitSet digitSet, bool ignoreContext=false) const

Binary Units

Not supported in QLocale.

enum BinarySizeUnits
enum BinaryUnitDialect

BinaryUnitDialect   binaryUnitDialect () const
void                setBinaryUnitDialect (BinaryUnitDialect newDialect)
QString             formatByteSize (double size) const
QString             formatByteSize (double size, int precision, BinaryUnitDialect dialect=KLocale::DefaultBinaryDialect, BinarySizeUnits specificUnit=KLocale::DefaultBinaryUnits) const

Measurement Systems

enum MeasureSystem

MeasureSystem  measureSystem()
void           setMeasureSystem(MeasureSystem value)

int   pageSize()
void  setPageSize(int paperFormat)

Encoding

QTextCodec        *codecForEncoding()
const QByteArray  encoding()
bool              setEncoding(int mibEnum)
int               encodingMib
int               fileEncodingMib()

Translations

Replace with QTranslator / tr() at lowest level, or new KTranslator at higher level.

QStringList     installedLanguages () const
bool            isApplicationTranslatedInto (const QString &language)

void            copyCatalogsTo (KLocale *locale)
void            insertCatalog (const QString &catalog)
void            removeCatalog (const QString &catalog)
void            setActiveCatalog (const QString &catalog)
static void     setMainCatalog (const char *catalog)

bool            useTranscript () const

QString         translateQt(const char *context, const char *sourceText, const char *comment) const
void            translateRaw(const char *singular, const char *plural, unsigned long n, QString *lang, QString *trans) const
void            translateRaw(const char *ctxt, const char *singular, const char *plural, unsigned long n, QString *lang, QString *trans) const
void            translateRaw(const char *msg, QString *lang, QString *trans) const
void            translateRaw(const char *ctxt, const char *msg, QString *lang, QString *trans) const
void            translateRawFrom(const char *catname, const char *msg, QString *lang, QString *trans) const
void            translateRawFrom(const char *catname, const char *singular, const char *plural, unsigned long n, QString *lang, QString *trans) const
void            translateRawFrom(const char *catname, const char *ctxt, const char *msg, QString *lang, QString *trans) const
void            translateRawFrom(const char *catname, const char *ctxt, const char *singular, const char *plural, unsigned long n, QString *lang, QString *trans) const

QString         localizedFilePath (const QString &filePath) const
static QString  langLookup (const QString &fname, const char *rtype="html")

bool    nounDeclension () const
QString removeAcceleratorMarker (const QString &label) const