v1.2.0.1-beta1
Locale

Description

Provides locale specific properties and formatted data.

The Locale object may only be created via the global locale() function. It cannot be created directly.

The global locale() function returns a JS Locale object representing the locale with the specified name, which has the format language[_territory][.codeset][@modifier] or C.

Locale supports the concept of a default locale, which is determined from the system's locale settings at application startup. If no parameter is passed to locale() the default locale object is returned.

The Locale object provides a number of functions and properties providing data for the specified locale.

The Locale object may also be passed to the Date and Number toLocaleString() and fromLocaleString() methods in order to convert to/from strings using the specified locale.

This example shows the current date formatted for the German locale:

var text = "The value is: " + Date().toLocaleString(locale("de_DE"));
Date prototype extension methods
string toLocaleString(locale, format)
Converts the Date to a string containing the date and time suitable for the specified locale in the s...

The following example displays the specified number in the correct format for the default locale:

var text = "The value is: " + Number(23443.34).toLocaleString(locale())
A few convenience methods to extend the standard Number prototype.
string toLocaleString(locale, format, precision)
Converts the Number to a string suitable for the specified locale in the specified format,...

Locale String Format Types

The monthName(), standaloneMonthName(), dayName() and standaloneDayName() can use the following enumeration values to specify the formatting of the string representation for a Date object.

  • Locale.LongFormat The long version of day and month names; for example, returning "January" as a month name.
  • Locale.ShortFormat The short version of day and month names; for example, returning "Jan" as a month name.
  • Locale.NarrowFormat A special version of day and month names for use when space is limited; for example, returning "J" as a month name. Note that the narrow format might contain the same text for different months and days or it can even be an empty string if the locale doesn't support narrow names, so you should avoid using it for date formatting. Also, for the system locale this format is the same as ShortFormat.

Date format specifiers

Besides the fixed format types listed above, a format string passed to the various Date formatting functions (Date.toLocaleString() and family) specifies a format string, it should use the following expressions to specify the date:

ExpressionOutput
dthe day as number without a leading zero (1 to 31)
ddthe day as number with a leading zero (01 to 31)
dddthe abbreviated localized day name (e.g. 'Mon' to 'Sun'). Uses QDate::shortDayName().
ddddthe long localized day name (e.g. 'Monday' to 'Qt::Sunday'). Uses QDate::longDayName().
Mthe month as number without a leading zero (1-12)
MMthe month as number with a leading zero (01-12)
MMMthe abbreviated localized month name (e.g. 'Jan' to 'Dec'). Uses QDate::shortMonthName().
MMMMthe long localized month name (e.g. 'January' to 'December'). Uses QDate::longMonthName().
yythe year as two digit number (00-99)
yyyythe year as four digit number

In addition the following expressions can be used to specify the time:

ExpressionOutput
hthe hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
hhthe hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
mthe minute without a leading zero (0 to 59)
mmthe minute with a leading zero (00 to 59)
sthe second without a leading zero (0 to 59)
ssthe second with a leading zero (00 to 59)
zthe milliseconds without leading zeroes (0 to 999)
zzzthe milliseconds with leading zeroes (000 to 999)
APuse AM/PM display. AP will be replaced by either "AM" or "PM".
apuse am/pm display. ap will be replaced by either "am" or "pm".
tinclude a time-zone indicator.

All other input characters will be ignored. Any sequence of characters that are enclosed in single quotes will be treated as text and not be used as an expression. Two consecutive single quotes (‘’'`) are replaced by a single quote in the output.

For example, if the following date/time value was specified:

// 21 May 2001 14:13:09
var dateTime = new Date(2001, 5, 21, 14, 13, 09);

This dateTime value could be passed to various Date formatting functions with values below to produce the following results:

FormatResult
"dd.MM.yyyy"21.05.2001
"ddd MMMM d yy"Tue May 21 01
"hh:mm:ss.zzz"14:13:09.042
"h:m:s ap"2:13:9 pm
See also
Date, Number

Properties

string amText
 
string decimalPoint
 
string exponential
 
enumeration firstDayOfWeek
 
string groupSeparator
 
enumeration measurementSystem
 
string name
 
string nativeCountryName
 
string nativeLanguageName
 
string negativeSign
 
enumeration numberOptions
 
string percent
 
string pmText
 
string positiveSign
 
enumeration textDirection
 
string zeroDigit
 
Array< int > weekDays
 
Array< string > uiLanguages
 

Public Member Functions

string currencySymbol (format)
 
string dateTimeFormat (type)
 
string dateFormat (type)
 
string timeFormat (type)
 
string monthName (month, type)
 
string standaloneMonthName (month, type)
 
string dayName (day, type)
 
string standaloneDayName (day, type)
 

Property Documentation

◆ amText

string amText
read

The localized name of the "AM" suffix for times specified using the conventions of the 12-hour clock.

◆ decimalPoint

string decimalPoint
read

Holds the decimal point character of this locale.

◆ exponential

string exponential
read

Holds the exponential character of this locale.

◆ firstDayOfWeek

enumeration firstDayOfWeek
read

Holds the first day of the week according to the current locale.

  • Locale.Sunday = 0
  • Locale.Monday = 1
  • Locale.Tuesday = 2
  • Locale.Wednesday = 3
  • Locale.Thursday = 4
  • Locale.Friday = 5
  • Locale.Saturday = 6

◆ groupSeparator

string groupSeparator
read

Holds the group separator character of this locale.

◆ measurementSystem

enumeration measurementSystem
read

This property defines which units are used for measurement.

  • Locale.MetricSystem This value indicates metric units, such as meters, centimeters and millimeters.
  • Locale.ImperialUSSystem This value indicates imperial units, such as inches and miles as they are used in the United States.
  • Locale.ImperialUKSystem This value indicates imperial units, such as inches and miles as they are used in the United Kingdom.
  • Locale.ImperialSystem Provided for compatibility. The same as Locale.ImperialUSSystem.

◆ name

string name
read

Holds the language and country of this locale as a string of the form "language_country", where language is a lowercase, two-letter ISO 639 language code, and country is an uppercase, two- or three-letter ISO 3166 country code.

◆ nativeCountryName

string nativeCountryName
read

Holds a native name of the country for the locale.

For example "España" for Spanish/Spain locale.

See also
nativeLanguageName

◆ nativeLanguageName

string nativeLanguageName
read

Holds a native name of the language for the locale.

For example "Schwiizertüütsch" for Swiss-German locale.

See also
nativeCountryName

◆ negativeSign

string negativeSign
read

Holds the negative sign character of this locale.

◆ numberOptions

enumeration numberOptions
read

Holds a set of options for number-to-string and string-to-number conversions.

See also
Number.toLocaleString()
Number.fromLocaleString()

◆ percent

string percent
read

Holds the percent character of this locale.

◆ pmText

string pmText
read

The localized name of the "PM" suffix for times specified using the conventions of the 12-hour clock.

◆ positiveSign

string positiveSign
read

Holds the positive sign character of this locale.

◆ textDirection

enumeration textDirection
read

Holds the text direction of the language:

  • Qt.LeftToRight
  • Qt.RightToLeft

◆ zeroDigit

string zeroDigit
read

Holds Returns the zero digit character of this locale.

◆ weekDays

Array< int > weekDays
read

Holds an array of days that are considered week days according to the current locale, where Sunday is 0 and Saturday is 6.

See also
firstDayOfWeek

◆ uiLanguages

Array< string > uiLanguages
read

Returns an ordered list of locale names for translation purposes in preference order.

The return value represents locale names that the user expects to see the UI translation in. The first item in the list is the most preferred one.

Member Function Documentation

◆ currencySymbol()

string currencySymbol ( format  )

Returns the currency symbol for the specified format:

  • Locale.CurrencyIsoCode a ISO-4217 code of the currency.
  • Locale.CurrencySymbol a currency symbol.
  • Locale.CurrencyDisplayName a user readable name of the currency.
See also
Number.toLocaleCurrencyString()

◆ dateTimeFormat()

string dateTimeFormat ( type  )

Returns the date time format used for the current locale.

type specifies the Locale String Format Types to return.

See also
Date

◆ dateFormat()

string dateFormat ( type  )

Returns the date format used for the current locale.

type specifies the Locale String Format Types to return.

See also
Date

◆ timeFormat()

string timeFormat ( type  )

Returns the time format used for the current locale.

type specifies the Locale String Format Types to return.

See also
Date

◆ monthName()

string monthName ( month  ,
type   
)

Returns the localized name of month (0-11), in the optional locale-format-type specified by type.

See also
dayName(), standaloneMonthName()

◆ standaloneMonthName()

string standaloneMonthName ( month  ,
type   
)

Returns the localized name of month (0-11) that is used as a standalone text, in the optional Locale String Format Types specified by type.

If the locale information doesn't specify the standalone month name then return value is the same as in monthName().

See also
monthName(), standaloneDayName()

◆ dayName()

string dayName ( day  ,
type   
)

Returns the localized name of the day (where 0 represents Sunday, 1 represents Monday and so on), in the optional Locale String Format Types specified by type.

See also
monthName(), standaloneDayName()

◆ standaloneDayName()

string standaloneDayName ( day  ,
type   
)

Returns the localized name of the day (where 0 represents Sunday, 1 represents Monday and so on) that is used as a standalone text, in the Locale String Format Types specified by type.

If the locale information does not specify the standalone day name then return value is the same as in dayName().

See also
dayName(), standaloneMonthName()