View source for 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().

A initial step has been made by replacing many <code>#include <klocale.h></code> references with <code>klocalizedstring.h</code> when i18n() is the only function required by a class.  Some other redundant includes will also be removed to leave only necessary code in place.

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

It should probably be made a requirement for all libraries migrated to the tiers that the KLocale => QLocale change is made.

=== 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.

The setters are documented at the bottom, most are not used anywhere, in the KDE repo.  Only those setters that are used have conversions documented below.

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 ====

{| style="font-family:monospace"
|-
! 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.


{| style="font-family:monospace"
|-
! 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.


{| style="font-family:monospace"
|-
! 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====

Note that formatDate() and readDate() should actually be accessed via the calendar() instance or KLocalizedDate and these will be documented separately.


{| style="font-family:monospace"
|-
! 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()
| Only calendar related classes
| -
| Should be added
|-
| void setCalendarSystem(CalendarSystem calendarSystem)
| Only calendar related classes
| -
| Use api parm
|-
| QString calendarType()
| Deprecated
| -
| -
|-
| void setCalendar(QString calendarType)
| Deprecated
| -
| -
|-
| QString dateFormat()
| Only calendar related classes
| QString dateFormat() - but different formats!
| QString dateFormat(FullPattern) - but different formats!
|-
| void setDateFormat(QString format)
| Only calendar related classes
| Use api parm
|
|-
| QString dateFormatShort()
| Only calendar related classes
| QString dateFormat(ShortFormat) - but different formats!
| QString dateFormat(ShortPattern) - but different formats!
|-
| void setDateFormatShort(QString format)
| Only calendar related classes
| Use api parm
|
|-
| QString timeFormat()
| Only calendar related classes
| QString timeFormat() - but different formats!
| QString timeFormat(FullPattern) - but different formats!
|-
| void setTimeFormat(QString format)
| Only calendar related classes
| Use api parm
|
|-
| bool dateMonthNamePossessive()
| Only calendar related classes
| Remove
|
|-
| void setDateMonthNamePossessive(bool possessive)
| -
| Remove
|
|-
| QString dayPeriodText(QTime &time, DateTimeComponentFormat format)
| Only calendar related classes
| amText() and pmText()
| New Qt dayPeriodText() api
|-
| int weekDayOfPray()
| Only calendar related classes
| Remove, try replace with weekend days instead
|
|-
| void setWeekDayOfPray(int day)
| -
| Remove, try replace with weekend days instead
|
|-
| WeekNumberSystem weekNumberSystem()
| Only calendar related classes
| Not supported
| New Qt api
|-
| void setWeekNumberSystem(WeekNumberSystem weekNumberSystem)
| -
| -
| Use new api parm
|-
| int weekStartDay()
| Only calendar related classes
| QList<Qt::DayOfWeek> weekdays()
|
|-
| void setWeekStartDay(int day)
| -
| -
| Use new api parm
|-
| int workingWeekEndDay()
| Only calendar related classes
| QList<Qt::DayOfWeek> weekdays()
|
|-
| void setWorkingWeekEndDay(int day)
| -
| -
| Use new api parm
|-
| int workingWeekStartDay()
| Only calendar related classes
| QList<Qt::DayOfWeek> weekdays()
|
|-
| void setWorkingWeekStartDay(int day)
| -
| -
| Use new api parm
|-
| bool use12Clock()
| -
| Remove
|
|-
| QString formatDate(QDate date, DateFormat format)
| templateinterface.cpp, khtmlview.cpp, knewstuff2/ui/itemsview.cpp
| QString toString(QDate date, FormatType format)
| QString toString(QDate date, FormatPattern format)
|-
| QDate readDate(QString str, bool *ok)
| kdatetable.cpp
| QDate toDate(QString string, FormatType format) - for ok uses date.isValid()
| QDate toDate(QString string, FormatPattern format) - for ok uses date.isValid()
|-
| QDate readDate(QString intstr, const QString fmt, bool *ok)
| -
| QDate toDate(QString string, QString format) - for ok uses date.isValid() - different formats!
|
|-
| QDate readDate(QString str, ReadDateFlags flags, bool *ok)
| -
| Not supported, use other methods
| New Qt api
|-
| QString formatLocaleTime(QTime pTime, TimeFormatOptions options)
| -
| QString toString(QTime time, QString format) or QString toString(QTime time, FormatType format)
| New Qt api???
|-
| QTime readLocaleTime(QString str, bool *ok, TimeFormatOptions options, TimeProcessingOptions processing)
| -
| QTime toTime(QString string, FormatType format) or QTime toTime(QString string, QString format)
| New Qt api???
|-
| QString formatTime(QTime pTime, bool includeSecs, bool isDuration)
| ktexteditor/templateinterface.cpp, ktimecombobox.cpp, kio/global.cpp
| QString toString(QTime time, QString format) or QString toString(QTime time, FormatType format)
| New Qt api???
|-
| QTime readTime(QString str, bool *ok)
| ktimecombobox.cpp
| QTime toTime(QString string, FormatType format) or QTime toTime(QString string, QString format)
| New Qt api???
|-
| QTime readTime(QString str, ReadTimeFlags flags, bool *ok)
| -
| QTime toTime(QString string, FormatType format) or QTime toTime(QString string, QString format)
| New Qt api???
|-
| QString formatDuration(unsigned long mSec)
| -
| Not supported
| New Qt api
|-
| QString prettyFormatDuration(unsigned long mSec)
| kdeui/jobs/kwidgetjobtracker.cpp
| Not supported
| New Qt api
|-
| QString formatDateTime(QDateTime dateTime, DateFormat format, bool includeSecs)
| Various
| QString toString(QDateTime dateTime, FormatType format)
| QString toString(QDateTime dateTime, FormatPattern format)
|-
| QString formatDateTime(KDateTime dateTime, DateFormat format, DateTimeFormatOptions options)
| -
| ???
| ???
|}

====Numbers====

Note that the QString methods now only apply the C locale, to localise properly you must use the QLocale methods.


{| style="font-family:monospace"
|-
! KLocale
! kdelibs
! Qt 5.0
! Qt 5.1
|-
| int decimalPlaces()
|
| Not in Qt
| Add to Qt
|-
| void setDecimalPlaces(int digits)
|
| Use precision parm of toString() methods - note defaults to 6 places!
| -
|-
| QString decimalSymbol()
|
| QChar decimalPoint()
| Add to Qt
|-
| void setDecimalSymbol(QString symbol)
|
| Create appropriate QLocale
| -
|-
| int fracDigits()
| Deprecated
| -
| -
|-
| void setFracDigits(int digits)
| Deprecated
| -
| -
|-
| QString negativeSign()
|
| QChar negativeSign()
| Add to Qt
|-
| void setNegativeSign(QString sign)
|
| Create appropriate QLocale
| -
|-
| QString positiveSign()
|
| QChar positiveSign()
| Add to Qt
|-
| void setPositiveSign(QString sign)
|
| Create appropriate QLocale
| -
|-
| QString thousandsSeparator()
|
| QChar groupSeparator()
| Add to Qt
|-
| void setThousandsSeparator(QString separator)
|
| Create appropriate QLocale
| -
|-
| QString formatLong(long num)
|
|
|
|-
| QString formatNumber(double num, int precision)
|
|
|
|-
| QString formatNumber(QString numStr, bool round, int precision)
|
|
|
|-
| double readNumber(QString numStr, bool *ok)
|
|
|
|}

====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

==== Setters Usage ====

Search using lxr of all places using KLocale setters.

Many hits, need more checks:

 setCountry()
 setEncoding()
 setLanguage()
 setLanguage()
 setPageSize()

Some uses, most are very simple to port away in KDE 4.9:

 setCalendar() - Date widgets, etc
 setCalendarSystem() - Date widgets, etc
 setDateFormat() - Some uses
 setDateFormatShort() - Clock Applet
 setTimeFormat() - Some uses
 setWeekStartDay() - KMyMoney

No real code, only kcm and tests

 setBinaryUnitDialect()
 setCountryDivisionCode()
 setCurrencyCode()
 setCurrencySymbol()
 setDateMonthNamePossessive()
 setDateTimeDigitSet()
 setDecimalPlaces()
 setDecimalSymbol()
 setDigitSet()
 setFracDigits()
 setMeasureSystem()
 setMonetaryDecimalPlaces()
 setMonetaryDecimalSymbol()
 setMonetaryDigitSet()
 setMonetaryThousandsSeparator()
 setNegativeMonetarySignPosition()
 setNegativePrefixCurrencySymbol()
 setNegativeSign()
 setPositiveMonetarySignPosition()
 setPositivePrefixCurrencySymbol()
 setPositiveSign()
 setThousandsSeparator()
 setWeekDayOfPray()
 setWeekNumberSystem()
 setWorkingWeekEndDay()
 setWorkingWeekStartDay()