Home · All Classes · Main Classes · Deprecated |
MLocale is a class that implements locale dependent data formatting as well as translation, collation and calendar systems. More...
Inherits QObject.
MLocale is a class that implements locale dependent data formatting as well as translation, collation and calendar systems.
For more general information about Internationalization in libmeegotouch see also the Internationalization Guidelines
The locale system in the MeeGo Touch UI Framework is separated into different categories. These correspond roughly to the LC_* environment variables of POSIX. MLocale is created with one main language setting but category settings can be used to override specific details. For example it is possible to set the main language to “en_US” to get user interface messages in English but set the MLcCollate category to “fi_FI” to get Finnish collation and set the MLcNumeric category to “de_DE” to get German number formatting.
The calendar system in the MeeGo Touch UI Framework supports a number of non-Gregorian calendar systems. The calendar is used to create presentations of date and time.
The collation system in the MeeGo Touch UI Framework supports a number of collation systems. The actual collation is done with the MCollator class.
The translation system in the MeeGo Touch UI Framework differs a bit from the usual practice used in any other translation system (e.g, Qt’s tr() or GNU’s gettext). In the MeeGo Touch UI Framework, a developer has to use both logical names and Engineering English to translate a string. Whenever no translation is available, the Engineering English version, which is auto-generated from the source code, is displayed instead of the logical names to make testing easier. The displayed Engineering English is prefixed with “!! ” to make it obvious that no translation was found and a proper translation still needs to be added. Internally, the MeeGo Touch UI Framework translation system uses the Qt translation system (using the QTranslator class). The translation source file is in .ts format version 3.0. Usually the translation source file is not generated from code, but rather generated by some other means (e.g from the UI specification).
If one wants to react when the locale settings are changed, one can connect to the settingsChanged() signal by using the connectSettings() method.
Type to select the strength of an MCollator object.
For an explanation of the collation strengths see the Unicode Collation Algorithm.
Return type for MCollator::compare(). Denotes the order of two strings.
Type for locale dependent date symbol presentation.
Chooses whether the returned name should be stand-alone or in context.
Example:
Using DateSymbolStandalone will select “sunnuntai” for Sunday in Finnish language whereas DateSymbolFormat will select the inflected form “sunnuntaina”.
Length type for date symbol presentation.
Chooses how much the returned name should be abbreviated.
Example:
For the first day of the week in English language, using DateSymbolAbbreviated will select “Sun”, using DateSymbolWide will select “Sunday”, and using DateSymbolNarrow will select “S”.
enum for Date formatting.
This correlates closely with the date type in ICU and Unicode CLDR. The values “DateShort”, “DateMedium”, “DateLong”, “DateFull”, have the same meaning as the respective data types in ICU.
The value “DateYearAndMonth” is a libmeegotouch addition to format only the year and the month without the day. “DateYearAndMonth” implies “TimeNone”. For example in Finnish locale the result of using “DateYearAndMonth” is something like “Joulukuu 2011” whereas in Chinese locale the result is something like “2011年 十二月”. This is useful for something like a month view in calendar where a headline showing the year and the month is needed but without the day because the days are shown in a table below the headline.
The value “DateWeekdayAbbreviatedAndDayOfMonth” is a libmeegotouch addition to format only the weekday name in abbreviated form and the day of the month. For example in Finnish locale the result of using “DateWeekdayAbbreviatedAndDayOfMonth” is something like “ma 5” whereas in Chinese locale it is something like “5日周一”.
The value “DateWeekdayWideAndDayOfMonth” is also a libmeegotouch addition, similar to “DateWeekdayAbbreviatedAndDayOfMonth”. It uses a longer format of the weekday name. For example in Finnish locale it would result in something like “maanantaina 5" whereas in Chinese locale it is something like “5日星期一”.
\ brief Grouping formats for phone numbers The phone number grouping specifies, how phone numbers will be displayed to the user. NoGrouping means that the phone numbers are not grouped at all. NorthAmericanGrouping means that the phone numbers are grouped according to the "North American Numbering Plan" DefaultGrouping means that grouping is done according to the current system settings.
Type to select 12 hour clock or 24 hour clock or default.
Chooses whether 12 hour clock or 24 hour clock should be forced or whether the default for the current locale should be used.
For example, the “en_US” locale uses a 12 hour clock by default, i.e. in case of “en_US”, both “LocaleDefaultTimeFormat24h“ and “TwelveHourTimeFormat24h” will have the effect that a 12 hour clock is used.
“TwentyFourHourTimeFormat24h” and “TwelveHourTimeFormat24h” will force the use of a 24 hour clock or 12 hour clock, respectively, no matter which one is used by default in this locale.
enum for Time formatting.
This correlates closely with the time type in ICU and Unicode CLDR
enum for weekday types
ML10N::MLocale::MLocale | ( | QObject * | parent = 0 |
) | [explicit] |
Constructs a MLocale as a copy of the current system default locale.
Constructs a MLocale with data copied from default Locale.
parent | the Object’s parent |
If MLocale is instantiated with this constructor, i.e. without the parameter specifying the locale name in ICU format as in the other constructor MLocale(const QString &localeName, QObject *parent), it will return a copy of the system default locale, if this already exists. If the system default locale does not exist yet, it is created based on the global settings in the relevant gconf keys. If the gconf settings are not available the system default locale is created based on the contents of the LANG environment variable.
The copy of the system default locale created may already have a list of translation catalogs installed, more translation catalogs can be added using installTrCatalog().
Constructs a MLocale from a ICU format locale ID string.
localeName | ICU format locale ID string. | |
parent | the Object’s parent |
For details about ICU format locale ID strings see http://userguide.icu-project.org/locale .
Locale ID | Language | Script | Country | Variant | Keywords | Comment |
---|---|---|---|---|---|---|
fi_FI | fi | FI | Finnish language in Finland, default sorting order | |||
fi_FI@collation=phonebook | fi | FI | collation=phonebook | Finnish language in Finland, phonebook sorting order | ||
zh_CN@collation=stroke;calendar=chinese | zh | CN | collation=stroke;calendar=chinese | Simplified Chinese with sorting via stroke-count and Chinese calendar |
ML10N::MLocale::~MLocale | ( | ) | [virtual] |
Destructor.
void ML10N::MLocale::addTranslationPath | ( | const QString & | path | ) | [static] |
Append a path to the translation file lookup directories.
If the path to be added is already in the list of translation paths, nothing happens, i.e. the path is not appended again to the end of the path list.
MLocale::CalendarType ML10N::MLocale::calendarType | ( | ) | const |
Returns calendar type.
Returns the country code of the locale category in ISO-3166 format.
same as country(), only for a specific category.
Returns the language code of the locale category in ISO-639 format.
same as language(), only for a specific category.
Returns the string representation of the locale category.
same as name(), only for a specific category.
The string representation of the locale category is the full ICU locale ID string. See the ICU user guide for examples.
Returns the script code of the locale category in ISO-15924 format.
same as script(), only for a specific category.
Returns the part of the locale category name which specifies the script in form of ISO 15924 script codes
If that part of the locale category name was not specified, i.e. if the default script for that language and country is used, it returns an empty string. For example, if the locale category name is “ru_RU”, an empty string is returned and not “Cyrl” which is the ISO 15924 code of the Cyrillic script used by the “ru_RU” locale.
If you need to find out which scripts are used by a certain locale use localeScripts() const instead.
Returns the variant of the locale category.
same as variant(), only for a specific category.
void ML10N::MLocale::clearSystemDefault | ( | ) | [static] |
MLocale::Collation ML10N::MLocale::collation | ( | ) | const |
Returns the collation mode.
MCollator ML10N::MLocale::collator | ( | ) | const |
Returns a MCollator which compares QStrings based on language/country/collation rules.
const MLocaleAbstractConfigItemFactory * ML10N::MLocale::configItemFactory | ( | ) | [static] |
Returns the factory that is used to create config items.
If there was no factory previously set or the factory is 0, a default MLocaleNullConfigItemFactory is created upon the first call to this function.
void ML10N::MLocale::connectSettings | ( | ) |
Monitors all changes in the locale related gconf keys.
After calling this method, all changes in the locale related gconf keys will change this locale according to the changes in the gconf keys, and emit the settingsChanged() signal.
void ML10N::MLocale::copyCatalogsFrom | ( | const MLocale & | other | ) |
Copies translations from another MLocale the catalogs are reloaded based on the locale settings.
QString ML10N::MLocale::country | ( | ) | const |
Returns the country code of the locale in ISO-3166 format.
If the country code cannot be parsed out of the locale name an empty string is returned.
Example: If the locale name is “fi_FI” this will return “FI”. If the locale name is “es_419” this will return “419”. “419” is the generic code for Latin American Spanisch. This “es_419” is used in the translations to have one common translation for all Latin American locales instead of individual ones like for all locales like “es_MX”.
QString ML10N::MLocale::countryEndonym | ( | ) | const |
Returns the endonym of the country of the locale.
The country endonym is the name of the country which is used by the inhabitants of that country.
English exonym | Language endonym |
---|---|
Germany | Deutschland |
Russia | Россия |
Japan | 日本 |
MLocale ML10N::MLocale::createCLocale | ( | ) | [static] |
returns a "C" locale
using this
MLocale locale = MLocale::createCLocale();
achieves the same as:
MLocale locale("en_US_POSIX");
libicu handles the string “en_US_POSIX” as synonym for posix locale behaviour.
MLocale * ML10N::MLocale::createSystemMLocale | ( | ) | [static] |
QStringList ML10N::MLocale::dataPaths | ( | ) | [static] |
Returns the list of data paths used by ICU.
QString ML10N::MLocale::decimalPoint | ( | ) | const |
returns the decimal point character of this locale.
Qt::LayoutDirection ML10N::MLocale::defaultLayoutDirection | ( | ) | [static] |
Static method to obtain the layout direction of the default locale.
This returns the layout direction of the system default locale, i.e. of the locale which has been set with setDefault().
See the longer explanation at textDirection() for what layout direction is returned depending on the locale id.
TimeFormat24h ML10N::MLocale::defaultTimeFormat24h | ( | ) | const |
Returns whether 24 hour or 12 hour format is used by default.
returns MLocale::TwelveHourTimeFormat24h if this locale would use 12 hour mode by default and MLocale::TwentyFourHourTimeFormat24h if this locale would use 24 hour mode by default.
Actually this locale may use a different mode because the default can be overridden, this method shows only what the default would be if it were not overridden.
Qt::LayoutDirection ML10N::MLocale::directionForText | ( | const QString & | text | ) | [static] |
Static method to obtain the text direction for a given text.
This returns the text direction for a (paragraph) of text according to the rules to determine the Paragraph Level in the Unicode Bidirectional Algorithm. I.e. it looks for the first character of L, AL, or R in the paragraph, if such a character is found and it is of type AL or R, the text direction is Qt::RightToLeft else Qt::LeftToRight.
If the text is empty or if it only contains digits, whitespace, punctuation characters or other characters with no strong text direction, this function returns Qt::LayoutDirectionAuto.
Notice that this will only work well for plain text; rich text might contain markup tags (e.g., <b>) that might also be detected as having a meaningful text direction.
void ML10N::MLocale::disconnectSettings | ( | ) |
Disconnects from change monitoring in settings After calling this method, all changes in the settings will no longer emit settingsChanged() signal.
QStringList ML10N::MLocale::exemplarCharactersIndex | ( | ) | const |
Returns a list of character or strings to be used in indices.
This returns an QStringList of characters (or character sequences) which can be used as index characters in user interfaces. Which index characters are useful depends on the locale set in lc_collation as the collation (sorting) rules depend on the locale.
For example, if lc_collation is set to Czech locale (i.e. if MLocale::categoryName(MLocale::MLcCollate) returns “cs_CZ”) this will return a list like:
“A B C Č D E F G H CH I J K L M N O P Q R Ř S Š T U V W X Y Z Ž”
Note that this also contains the character sequence “CH” as an index “character” because in Czech CH is sorted as if it were a single character after H. Therefore, CH deserves its own entry in a collation index for Czech.
Formats an amount of currency.
amount | amount to format | |
currency | three letter currency code in ISO-4217 format, e.g. EUR or USD |
QString ML10N::MLocale::formatDateTime | ( | const QDateTime & | dateTime, | |
DateType | dateType = DateLong , |
|||
TimeType | timeType = TimeLong , |
|||
CalendarType | calendarType = DefaultCalendar | |||
) | const |
Creates a string presentation for a date time with explicit format lengths.
dateTime | time object to create representation from | |
dateType | style of date formatting | |
timeType | style of time formatting | |
calendarType | calendar type to use for formatting |
If dateType is MLocale::DateNone and timeType is MLocale::TimeNone, an empty string is returned.
Using this can be considerably slower than using formatDateTime(const MCalendar &mCalendar, DateType datetype = DateLong, TimeType timetype = TimeLong) const, see the example there.
QString ML10N::MLocale::formatDateTime | ( | const QDateTime & | dateTime, | |
CalendarType | calendarType | |||
) | const |
String presentation with explicit calendar type.
dateTime | time to format | |
calendarType | calendar to use |
This uses the TimeLong and DateLong formats.
Using this can be considerably slower than using formatDateTime(const MCalendar &mCalendar, DateType datetype = DateLong, TimeType timetype = TimeLong) const, see the example there.
QString ML10N::MLocale::formatDateTime | ( | const MCalendar & | mCalendar, | |
DateType | datetype = DateLong , |
|||
TimeType | timetype = TimeLong | |||
) | const |
Formats MCalendar using its native calendar system.
mCalendar | Calendar holding the datetime to format | |
datetype | format for date | |
timetype | format for time |
If dateType is MLocale::DateNone and timeType is MLocale::TimeNone, an empty string is returned.
The return value of this method does not necessarily start with an uppercase letter because it cannot know in which context the returned string will be used. Therefore, it is left to the application to uppercase the first letter if the context requires is. Uppercasing the first letter could be done as in the following example:
QString formattedDateTime; QDateTime current = QDateTime::currentDateTime(); MLocale locale; MCalendar calendar; calendar.setDateTime(current); formattedDateTime = locale.formatDateTime(calendar, MLocale::DateMedium, MLocale::TimeMedium); // Make the first letter uppercase: if (!formattedDateTime.isEmpty()) formattedDateTime[0] = locale.toUpper(formattedDateTime.at(0))[0];
If many dates and times need to be formatted, this method should be preferred over formatDateTime(const QDateTime &dateTime, DateType dateType = DateLong, TimeType timeType = TimeLong, CalendarType calendarType = DefaultCalendar) const because the latter one creates an MCalendar and sets it to the QDateTime. It is wasteful to create a new MCalendar many times, it is better to create the MCalendar only once, change the date and time of this calendar as needed and use this MCalendar for formatting. Example:
QString formattedDateTime; QDateTime current = QDateTime::currentDateTime(); MLocale locale; MCalendar calendar; for(int i=0 ; i < 5000 ; i++) { current.addSecs(36); calendar.setDateTime(current); formattedDateTime = locale.formatDateTime(calendar, MLocale::DateMedium, MLocale::TimeMedium); }
QString ML10N::MLocale::formatDateTime | ( | const QDateTime & | dateTime, | |
const QString & | formatString | |||
) | const |
QString ML10N::MLocale::formatDateTime | ( | const MCalendar & | mCalendar, | |
const QString & | formatString | |||
) | const |
Formats a date string based on ISO-14652 (draft) pattern.
For more information about the format characters used here see ISO-14652 (draft) or the man page of “date” or the documentation of the glibc function “strftime” .
The pattern may contain the following symbols to be replaced with the corresponding information:
QString ML10N::MLocale::formatDateTimeICU | ( | const QDateTime & | dateTime, | |
const QString & | formatString | |||
) | const |
QString ML10N::MLocale::formatDateTimeICU | ( | const MCalendar & | mCalendar, | |
const QString & | formatString | |||
) | const |
QString ML10N::MLocale::formatNumber | ( | short | i | ) | const |
Returns the string representation of a number.
i | number to format |
QString ML10N::MLocale::formatNumber | ( | int | i | ) | const |
Returns the string representation of a number.
i | number to format |
QString ML10N::MLocale::formatNumber | ( | qlonglong | i | ) | const |
Returns the string representation of a number.
i | number to format |
QString ML10N::MLocale::formatNumber | ( | double | i, | |
int | maxPrecision = -1 | |||
) | const |
Returns the string representation of a number.
i | number to format | |
maxPrecision | maximum number of fractional digits |
This just calls formatNumber(i, maxPrecision, 0).
QString ML10N::MLocale::formatNumber | ( | double | i, | |
int | maxPrecision, | |||
int | minPrecision | |||
) | const |
Returns the string representation of a number.
i | number to format | |
maxPrecision | maximum number of fractional digits | |
minPrecision | minimum number of fractional digits |
minPrecision is bound to be between 0 and maxPrecision inclusive.
QString ML10N::MLocale::formatNumber | ( | float | i | ) | const |
Returns the string representation of a number.
i | number to format |
Examples:
// format a number to a string according to the conventions of the // current system default locale: MLocale locale; // gets the current system default locale QString numberString = locale.formatNumber(12345670.89);
// format a number to a string using US English conventions no // matter what the current system default locale is: MLocale locale("en_US"); QString numberString = locale.formatNumber(12345670.89); // now numberString contains “12,345,670.89”
QString ML10N::MLocale::formatPercent | ( | double | i, | |
int | decimals = 0 | |||
) | const |
Returns the string representation of a number as percentage.
i | number to format | |
decimals | number of digits shown after decimal separator |
Example:
MLocale locale; // gets the current system default locale QString percentString = locale.formatPercent(0.0123, 2);
locale | double value | decimals | result |
---|---|---|---|
en_US | 0.0123 | 2 | 1.23% |
en_US | 12.3456789 | 4 | 1,234.5679% |
de_CH | 12.3456789 | 4 | 1'234.5679% |
tr_TR | 12.3456789 | 4 | % 1.234,5679 |
QString ML10N::MLocale::formatPhoneNumber | ( | const QString & | phoneNumber, | |
PhoneNumberGrouping | grouping = DefaultPhoneNumberGrouping | |||
) | const |
Formats a phone number according to the given grouping.
MLocale & ML10N::MLocale::getDefault | ( | ) | [static, protected] |
Returns the default locale object.
QString ML10N::MLocale::icuFormatString | ( | DateType | dateType = DateLong , |
|
TimeType | timeType = TimeLong , |
|||
CalendarType | calendarType = DefaultCalendar | |||
) | const |
returns ICU date and time format string of the current locale
dateType | style of date formatting | |
timeType | style of time formatting | |
calendarType | calendar to use for formatting |
Returns the name of an appropriate sort bucket for a string.
This function is useful to get index titles when sorting a large amount of strings like in a telephone book, a list of videos etc. The list of useful index titles is language specific, for example for Czech (“cs_CZ” locale) it is
“A B C Č D E F G H CH I J K L M N O P Q R Ř S Š T U V W X Y Z Ž”
for Japanese (“ja_JP=standard” locale, same as “ja_JP”) it is
“あ か さ た な は ま や ら わ”
and for traditional Chinese (“zh_TW=stroke”, same as “zh_TW”) locale it is
“一 丁 三 丑 丙 丞 串 並 亟 乘 乾 傢 亂 僧 億 儒 優 叢 嚥 勸 儷 儼 囌 囑 廳”
This function is helpful to find out which bucket a string will be sorted into when sorting locale aware.
Examples for “cs_CZ” locale:
String | Bucket |
---|---|
cesta | C |
češtinǎ | Č |
chemie | CH |
ů | U |
α | Α |
Α | Α |
沙紀 | 沙 |
Examples for “ja_JP=standard” locale:
String | Bucket |
---|---|
richard | R |
さき | さ |
ジョン | さ |
はなこ | は |
Examples for “zh_TW=stroke” locale:
String | Bucket |
---|---|
John | J |
宁驰 | 丙 |
柳 君蘅 | 亟 |
As can be seen in the above examples, this function tries to return useful extra buckets for strings which sort out of the range of the bucket list of the language of the current locale. For example if one is running in Czech locale but has also some Japanese and some Greek names in the contact list these foreign strings sort outside of the range of the Czech bucket list. This function tries to create useful extra buckets for these foreign strings.
For applications using an MAbstractItemModel, it is probably more convenient to use the MLocaleBuckets class that uses this function internally.
QString ML10N::MLocale::indexBucket | ( | const QString & | str, | |
const QStringList & | buckets, | |||
const MCollator & | collator | |||
) | const |
Internal version of MLocale::indexBucket().
str | String to find a bucket for | |
buckets | bucket list (result of MLocale::exemplarCharactersIndex()) | |
collator | collator to use for sorting. |
This overloaded function is more efficient if a large number of index buckets is to be retrieved since it can re-use the buckets list and the collator from one call to the next. Before the first call, initialize the 'buckets' list with MLocale::exemplarCharactersIndex().
On top of that, please take care to set the strength of the collator passed as an argument to primary strength, if this is not done the resulting buckets will be slightly wrong.
But use primary strength only for the collator used to get the buckets, not for the collator used to do the actual sorting. The collator used to do the actual sorting should be set to quaternary strength in most cases.
For an explanation of the collation strengths see the Unicode Collation Algorithm.
Example:
MLocale locale; // gets the current system default locale MCollator collator = locale.collator(); // IMPORTANT: don’t forget to set the collator for the buckets to // primary strength: collator.setStrength(MLocale::CollatorStrengthPrimary); QStringList buckets = locale.exemplarCharactersIndex(); // now you can find the index bucket for a name, for example // in case of “Abraham”, the bucket will be “A” in “en_US” locale and most // other locales. QString bucket = indexBucket(QString::fromUtf8("Abraham"), buckets, collator);
void ML10N::MLocale::installTrCatalog | ( | const QString & | name | ) |
installs a translation catalog
name | of the translation catalog to install |
Adds this translation catalog to the list of translation catalogs used by this MLocale.
The list of catalogs used by the system default locale is the list of catalogs which will be used when translating strings with qtTrId() or tr().
Usually the catalog name should be specified without the “.qm” file extension and without the locale specific part of the file name. I.e. one should usually call installTrCatalog("foo") and not installTrCatalog("foo_en_US.qm").
If only the basename of the catalog (e.g. "foo") is specified, installTrCatalog() installs both the engineering English file for this catalog and the real translations for this catalog for the locale. The engineering English gets lowest priority by prepending it to the list of already installed catalogs and the real translations get highest priority by appending it to the list of already installed catalog names.
Example:
Add translation catalogs “foo” and “bar” to the catalogs used by the system default locale:
// get current system default locale MLocale locale; // install a translation catalog // (this catalog is added to the list of catalogs already used // by the system default locale): locale.installTrCatalog("foo"); locale.installTrCatalog("bar"); // make the locale with the added translation catalog the new system // default: MLocale::setDefault(locale);
In this example, after calling locale.installTrCatalog("foo") the internal list of installed catalog names of the locale looks like:
"foo.qm" "bar.qm" ... previous catalog list ... "foo" "bar"
Priority in this list increases from left to right.
Eventually, this list of catalog names is evaluated and translation files are loaded from the file system. The translation files are searched in the directories in the translation path list, see translationPaths().
For entries in the list of catalog names which end with “.qm” the names are used “as is”, i.e. in the example above the files “foo.qm” and “bar.qm” are loaded for these entries. For entries in the list of catalog names which do not end with “.qm”, a locale specific file name part and a “.qm” extension is added and Qt-like fallbacks for the file name to load are used. As an example, let’s assume that the name of the locale is “en_US”, then the following file names are tried to get the real translations for the catalog name “foo”:
foo_en_US.qm foo_en_US foo_en.qm foo_en
and the first one which exists is loaded.
Note that the search for fallbacks for the real translation stops at “foo_en”. This is slightly different from the behaviour of QTranslator::load() because proceeding to the fallback “foo.qm” would load engineering English if “foo.qm” exists which is not what we want when trying to load real translations because this might add engineering English with the wrong priority (highest priority) to the list of translation catalogs if the real translation happens to be missing.
If the settings of the locale change, the list of translation catalog names is reevaluated and translations may switch to a different language (see connectSettings(), disconnectSettings(), settingsChanged(), localeSettingsChanged()).
If a full file name including a “.qm” extension is specified as the argument of installTrCatalog(), this catalog name is always appended to the list of catalog names, i.e. used with highest priority. This means that after calling locale.installTrCatalog("foo_en_US.qm") the internal list of installed catalog names looks like:
... previous catalog list ... "foo_en_US.qm"
This is mainly intended for testing to force loading of a fully specified translation file with highest priority. Except for testing this should not be used because in the above example with “foo_en_US.qm”, the locale specific part does not change according to the locale settings but always stays like this. And loading an engineering English file by specifying the full file name, i.e. installTrCatalog("foo.qm") should also be used only for testing because this adds the engineering English with highest priority which is usually wrong.
After a locale has been made the system default with setDefault(), the translation catalogs which have been installed into that locale are available for use with qtTrId(), i.e. one can use code like this to translate a string:
// translate a string: //% "Hello" QString translatedString = qtTrId("hello_msg");
bool ML10N::MLocale::isInstalledTrCatalog | ( | const QString & | name | ) | const |
checks whether a translation catalog is installed nor not
name | of the translation catalog to check |
returns true if such a translation catalog has been installed already, false if not.
bool ML10N::MLocale::isValid | ( | ) | const |
Returns true if MLocale is valid and can be used.
QString ML10N::MLocale::joinStringList | ( | const QStringList & | texts | ) | const |
join a list of strings according to the conventions of the locale
texts | the texts to be joined |
This method is intended to join a list of strings with commas according to the conventions of the locale. For example, if you want to join a list of names like
“John Doe”, “Judy Roe”, “James Doe”
the result might be “John Doe, Judy Roe, James Doe” in English and many other locales, but for example in Arabic locales or Chinese locales, different versions of the comma may be used.
On top of that, if the list contains both texts in left-to-right scripts and texts right-to-left scripts, texts which have a different direction then the firsts text maybe reordered strangely if all texts are only joined with some separator. Especially if the texts to be joined contain symbols, for example parentheses, weird bidi reordering may happen. To prevent nonsensical bidi reordering, the direction of each text in the list is checked and directional markers are inserted to make sure each individual text is reordered correctly.
QString ML10N::MLocale::language | ( | ) | const |
QString ML10N::MLocale::languageEndonym | ( | ) | const |
Returns the endonym of the language of the locale.
The language endonym is the name of the language which is used by the native speakers of this language.
English exonym | Language endonym |
---|---|
German | Deutsch |
Russian | русский язык |
Japanese | 日本語 |
Static method to obtain endonym for locale. Can be used to obtain endonym without instantiating MLocale, useful when obtaining a list of endonyms for a lot of languages.
QStringList ML10N::MLocale::localeScripts | ( | ) | const |
Returns the list of scripts used by the locale.
This returns the scripts used by the locale, in form of ISO 15924 script codes. Most locales use only one script but there are a few locales which use several scripts.
locale name | script codes |
---|---|
en_US | Latn |
sr_RS | Cyrl |
sr_Cyrl_RS | Cyrl |
sr_Latn_RS | Latn |
zh_Hant_TW | Hani, Bopo |
ja_JP | Kana, Hira, Hani |
void ML10N::MLocale::localeSettingsChanged | ( | ) | [signal] |
Signal emitted when the default system locale changes.
QString ML10N::MLocale::monthName | ( | const MCalendar & | mCalendar, | |
int | monthNumber, | |||
DateSymbolContext | context, | |||
DateSymbolLength | symbolLength | |||
) | const |
Returns the locale dependent name for a month choosing context and length.
Returns the locale dependent name for a month number.
calls the 4 argument version of monthName() with context = MLocale::DateSymbolStandalone and symbolLength = MLocale::DateSymbolWide
QString ML10N::MLocale::name | ( | ) | const |
Returns the string representation of the locale.
The string representation of the locale is the full ICU locale ID string. See the ICU user guide for examples.
QDateTime ML10N::MLocale::parseDateTime | ( | const QString & | dateTime, | |
CalendarType | calendarType | |||
) | const |
Creates a datetime object from a string with explicit calendar type.
dateTime | string to parse | |
calendarType | calendar to use |
QDateTime ML10N::MLocale::parseDateTime | ( | const QString & | dateTime, | |
DateType | dateType = DateLong , |
|||
TimeType | timeType = TimeLong , |
|||
CalendarType | calendarType = DefaultCalendar | |||
) | const |
Creates a datetime object from a string with explicit format lengths.
dateTime | string to parse | |
dateType | style of date formatting | |
timeType | style of time formatting | |
calendarType | calendar to use for formatting |
If dateType is MLocale::DateNone and timeType is MLocale::TimeNone, an invalid QDateTime is returned.
void ML10N::MLocale::removeTranslationPath | ( | const QString & | path | ) | [static] |
Removes a path.
void ML10N::MLocale::removeTrCatalog | ( | const QString & | name | ) |
removes a translation catalog
name | of the translation catalog to remove |
Removes the catalog from the list of translation catalogs used by this MLocale.
QString ML10N::MLocale::script | ( | ) | const |
Returns the script code of the locale in ISO-15924 format.
Returns the part of the locale name which specifies the script in form of ISO 15924 script codes
If that part of the locale name was not specified, i.e. if the default script for that language and country is used, it returns an empty string. For example, if the locale name is “ru_RU”, an empty string is returned and not “Cyrl” which is the ISO 15924 code of the Cyrillic script used by the “ru_RU” locale.
If you need to find out which scripts are used by a certain locale use localeScripts() const instead.
void ML10N::MLocale::setCalendarType | ( | CalendarType | calendar | ) |
Sets calendar type.
Sets category with specified locale string.
localeName | ICU format locale ID string. |
void ML10N::MLocale::setCollation | ( | Collation | collation | ) |
Sets the collation mode.
void ML10N::MLocale::setConfigItemFactory | ( | const MLocaleAbstractConfigItemFactory * | factory | ) | [static] |
Tells MLocale to use this factory to create config items
A MLocaleAbstractConfigItem is an abstraction from the way how MLocale gets and sets config values of the system. These can be for example the current language or region of the system. Users of the MLocale library can implement a factory if needed. for an example look at the MLocaleGConfConfigItemFactory.
void ML10N::MLocale::setDataPath | ( | const QString & | dataPath | ) | [static] |
Sets the data paths used by ICU to the given path.
dataPath | the data path |
convenience function to set the data path used by ICU to a single directory
void ML10N::MLocale::setDataPaths | ( | const QStringList & | dataPaths | ) | [static] |
Sets the DataPaths for the (ICU) locale system to the given paths.
dataPaths | a list of paths |
This should be called at most once in a process before creating any MLocale instances. This function is not thread-safe. Use it before doing anything with MLocale instances from multiple threads.
This function calls u_setDataDirectory() in libicu, see also http://icu-project.org/apiref/icu4c/putil_8h.html.
libmeegotouch initialises this data path to the value of the macro
M_ICUEXTRADATA_DIR
which is normally set to
/usr/share/mlocale/icu/
usually one should not change this.
The user data itself should be in the ICU specific subdirectories at the given paths, e.g. a user override file for some of the basic data of the Finnish locale should be in
/usr/share/mlocale/icu/usrdt42l/fi.res
and a user override file for the lang data of the Finnish locale should be in
/usr/share/mlocale/icu/usrdt42l/lang/fi.res
etc.
void ML10N::MLocale::setDefault | ( | const MLocale & | locale | ) | [static] |
Sets the default locale.
void ML10N::MLocale::setTimeFormat24h | ( | TimeFormat24h | timeFormat24h | ) |
Sets whether 24 hour clock, 12 hour clock or default is used.
timeFormat24h | enum to choose the 12/24 hour mode |
If MLocale::TwelveHourTimeFormat24h is given as the parameter the locale is forced to use 24 hour mode, if MLocale::TwentyFourHourTimeFormat24h is given as the parameter the locale is forced to use 12 hour mode. If MLocale::LocaleDefaultTimeFormat24 is given as the parameter the locale is neither forced to use 12 nor 24 hour mode, it uses the default for this locale then.
void ML10N::MLocale::settingsChanged | ( | ) | [signal] |
void ML10N::MLocale::setTranslationPaths | ( | const QStringList & | paths | ) | [static] |
Sets the paths that are used as base directories for using translations The translation path modification methods are not thread-safe.
The default translation path is
* /usr/share/l10n/meegotouch *
i.e. if none of the translation path modification methods is used, the list of translation paths contains only this entry.
Qt::LayoutDirection ML10N::MLocale::textDirection | ( | ) | const |
Returns the text direction of the locale.
This function unfortunately has a confusing name, it is not the direction of a certain amount of text, which is detected by directionForText(const QString &text). For a purely Arabic text for example, directionForText() will always return Qt::RightToLeft no matter what the current locale is (it is a static function, thus independent of the current locale, the result only depends on th text given as an argument).
This function here actually returns the layout direction for the current locale.
The layout direction of the QApplication is set to what textDirection() returns for the system default locale (which can be set with setDefault(const MLocale &locale)).
The layout direction returned here used to be Qt::RightToLeft for locales which use RTL scripts (e.g. Arabic, Hebrew, ...) and Qt::LeftToRight for locales which use LTR scripts (e.g. English, Chinese, Russian, ...)
Now this has changed because it has been requested to disable layout reversal by default, therefore this function will always return Qt::LeftToRight by default now, even for locales with RTL scripts like Arabic or Hebrew.
This new behaviour can be overridden by setting the option “layout-direction” in the full locale name. “layout-direction=rtl” forces right-to-left layout direction “layout-direction=ltr” forces left-to-right layout direction and “layout-direction=auto” sets the layout direction to the direction of the script used by the locale, i.e. “layout-direction=auto” reproduces the previous behaviour.
Examples:
Locale ID | textDirection() | defaultLayoutDirection() |
---|---|---|
ar_EG | Qt::LeftToRight | Qt::LeftToRight |
ar_EG@layout-direction=ltr | Qt::LeftToRight | Qt::LeftToRight |
ar_EG@layout-direction=rtl | Qt::RightToLeft | Qt::RightToLeft |
ar_EG@layout-direction=auto | Qt::RightToLeft | Qt::LayoutDirectionAuto |
en_US | Qt::LeftToRight | Qt::LeftToRight |
en_US@layout-direction=ltr | Qt::LeftToRight | Qt::LeftToRight |
en_US@layout-direction=rtl | Qt::RightToLeft | Qt::RightToLeft |
en_US@layout-direction=auto | Qt::LeftToRight | Qt::LayoutDirectionAuto |
MLocale::TimeFormat24h ML10N::MLocale::timeFormat24h | ( | ) | const |
Returns whether 24 hour clock, 12 hour clock or default is used.
returns MLocale::TwelveHourTimeFormat24h if 12 hour mode is forced for this locale, returns MLocale::TwentyFourHourTimeFormat24h if 24 hour mode is forced for this locale and returns MLocale::LocaleDefaultTimeFormat24h if the 12/24 hour mode is not forced but left to what this locale would use by default.
double ML10N::MLocale::toDouble | ( | const QString & | s, | |
bool * | ok = 0 | |||
) | const |
Returns the double represented by a localized string.
s | localized string to parse | |
ok | pointer to a bool indicating success or failure |
If ok is not NULL, reports failure by setting *ok to false and success by setting *ok to true.
float ML10N::MLocale::toFloat | ( | const QString & | s, | |
bool * | ok = 0 | |||
) | const |
Returns the float represented by a localized string.
s | localized string to parse | |
ok | pointer to a bool indicating success or failure |
If ok is not NULL, reports failure by setting *ok to false and success by setting *ok to true.
int ML10N::MLocale::toInt | ( | const QString & | s, | |
bool * | ok = 0 | |||
) | const |
Returns the int represented by a localized string.
s | localized string to parse | |
ok | pointer to a bool indicating success or failure |
If ok is not NULL, reports failure by setting *ok to false and success by setting *ok to true.
converts all localized digits in the input to Latin digits
text | a string which may contain various localized digits |
This is static, i.e. it does not depend on a specific locale.
It converts all sorts of localized digits, for example Eastern Arabic digits, Devanagari digits, CJK full-width digits ... to the usual Latin digits.
On top of that, it removes directional formatting codes like RLM markers, strings containing numbers in Arabic may contain such markers, they should be removed when converting to Latin numbers.
Other characters in the input apart from digits and directional formatting codes are returned unchanged.
QString ML10N::MLocale::toLocalizedNumbers | ( | const QString & | text, | |
const QString & | targetDigits | |||
) | [static] |
converts all localized digits in the input to the given localized digits
text | a string which may contain various localized digits | |
targetDigits | a string of length 10 containing the target digits |
This is static, i.e. it does not depend on a specific locale.
It converts all sorts of localized digits, for example Eastern Arabic digits, Devanagari digits, CJK full-width digits ... to the digits in the string given as the second parameter. The string given as the second parameter must have exactly a length of 10 specifying the digits of the desired target numbering system.
Only digits are changed, nothing else, except if the target digits are "0123456789", i.e. Latin digits, then it removes directional formatting codes as well, i.e. it behaves like like toLatinNumbers(const QString &text).
converts all digits in the input to localized digits
text | a string which may contain various localized digits |
This converts all digits in the input, whether they are already localized or not, into digits localized for the current locale.
For example, if the input contains Devanagari digits and Latin digits, and if the current locale uses Eastern Arabic digits, both the Devanagari digits and the Latin digits are converted to Eastern Arabic digits.
Only digits are changed, nothing else, except if the target digits are Latin digits, then it behaves like toLatinNumbers(const QString &text) which removes directional formatting codes as well.
qlonglong ML10N::MLocale::toLongLong | ( | const QString & | s, | |
bool * | ok = 0 | |||
) | const |
Returns the qlonglong represented by a localized string.
s | localized string to parse | |
ok | pointer to a bool indicating success or failure |
If ok is not NULL, reports failure by setting *ok to false and success by setting *ok to true.
locale-aware and context-sensitive conversion to lowercase
string | the string to convert to lowercase |
returns the lowercased string.
Use this instead of QString::toLower() if locale-aware and context-sensitive conversion to lowercase is required.
This is implemented using libicu, if libmeegotouch is compiled without libicu, QString::toLower() is used as a fallback.
QString::toLower() is not locale-aware and not context-sensitive, i.e. neither the locale nor the context influence its behaviour.
Therefore, it does not work correctly for Greek, where the character "Σ" (capital sigma) lowercases to either "ς" (small final sigma) or "σ" (small sigma) depending on whether the capital sigma is the last letter in a word. (It is context-dependent.)
Neither does it work for Lithuanian and Turkic languages where a “combining dot above” character may need to be removed in certain cases. (It “contracts” and is language- and context-dependent.)
For details see Unicode Case Mappings.
short ML10N::MLocale::toShort | ( | const QString & | s, | |
bool * | ok = 0 | |||
) | const |
Returns the short represented by a localized string.
s | localized string to parse | |
ok | pointer to a bool indicating success or failure |
If ok is not NULL, reports failure by setting *ok to false and success by setting *ok to true.
locale-aware, context-sensitive conversion to uppercase
string | the string to convert to uppercase |
returns the uppercased string.
Use this instead of QString::toUpper() if locale-aware and context-sensitive conversion to lowercase is required.
This is implemented using libicu, if libmeegotouch is compiled without libicu, QString::toUpper() is used as a fallback.
QString::toUpper() is not locale-aware and not context-sensitive, i.e. neither the locale nor the context influence its behaviour.
QString ML10N::MLocale::translate | ( | const char * | context, | |
const char * | sourceText, | |||
const char * | comment = 0 , |
|||
int | n = -1 | |||
) |
tr() compatibility translation method.
context | context of the translation | |
sourceText | text to translate | |
comment | about the translation. may be helpful when creating translation files | |
n | plurality |
QStringList ML10N::MLocale::translationPaths | ( | ) | [static] |
Returns the list of current translation file base paths.
QString ML10N::MLocale::variant | ( | ) | const |
Returns the variant of the locale.
If the variant code cannot be parsed out of the locale name an empty string is returned.
Example: If the locale name is sr_Latn_RS_REVISED@currency=USD
this will return REVISED
.
Returns locale dependent weekday name.
calls the 4 argument version of weekdayName() with context = MLocale::DateSymbolStandalone and symbolLength = MLocale::DateSymbolWide
QString ML10N::MLocale::weekdayName | ( | const MCalendar & | mCalendar, | |
int | weekday, | |||
DateSymbolContext | context, | |||
DateSymbolLength | symbolLength | |||
) | const |
Returns locale dependent weekday name choosing context and length.
Copyright © 2010 Nokia Corporation | MeeGo Touch |