Skip to main content

Locales class

๐Ÿ“– Descriptionโ€‹

The Locales class holds locale information and contains functions to format dates and numbers.

๐Ÿ“Œ Static fieldsโ€‹


๐Ÿท๏ธ countryโ€‹

Retrieves the country for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ countryCodeโ€‹

Retrieves the country code for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ countryNativeโ€‹

Retrieves the native country name for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ directionโ€‹

Retrieves the text direction for the current active locale.

Typeโ€‹

"ltr" | "rtl"


๐Ÿท๏ธ domainโ€‹

Retrieves the domain for the current locale.

Typeโ€‹

string


๐Ÿท๏ธ domainsโ€‹

Retrieves a list of domains. Each domain contains the locale, language and native language string.

Typeโ€‹

IDomain[]


๐Ÿท๏ธ identifierโ€‹

Retrieves the locale identifier string.

Typeโ€‹

string


๐Ÿท๏ธ languageโ€‹

Retrieves the language for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ languageNativeโ€‹

Retrieves the language in the native language for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ localeโ€‹

Retrieves the locale information for the current active locale.

Typeโ€‹

ILocale


๐Ÿท๏ธ localesโ€‹

Retrieves a list of supported locales.

Typeโ€‹

string[]

๐Ÿ“Œ Static methodsโ€‹


๐Ÿ”ง dateFullโ€‹

Formats to a localized full date string (for example, Wednesday, March 23, 2022).

Signatureโ€‹

dateFull(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateLongโ€‹

Formats to a localized long date string (for example, March 23, 2022).

Signatureโ€‹

dateLong(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateMediumโ€‹

Formats to a localized medium date string (for example, Mar 23, 2022).

Signatureโ€‹

dateMedium(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateShortโ€‹

Formats to a localized short date string (for example, 3/23/22).

Signatureโ€‹

dateShort(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateTimeโ€‹

Formats a date/time to a localized string.

Signatureโ€‹

dateTime(format: string, time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
formatstringNoSpecifies the format to use, using the CLDR date/time formatting style. The following variables are available:
- y / yyyy: Specifies the full 4-digit year;
- yy: Specifies the 2-digit year;
- M: Specifies the month number;
- MM: Specifies the month number with a minimum of 2 digits;
- MMM: Specifies the month as an abbreviated string (e.g. Jan);
- MMMM: Specifies the month as a full string (e.g. January);
- MMMMM: Specifies the month as a narrow (e.g. J);
- LLL: Specifies the month as an abbreviated nominative string (e.g. Jan);
- LLLL: Specifies the month as a full nominative string (e.g. January);
- LLLLL: Specifies the month as a narrow nominative string (e.g. J);
- d: Specifies the day of the month;
- dd: Specifies the day of the month with a minimum of 2 digits;
- E: Specifies the day of the week;
- EE: Specifies the day of the week as a string (e.g. Su);
- EEE: Specifies the day of the week as an abbreviated string (e.g. Sun);
- EEEE: Specifies the day of the week as a full string (e.g. Sunday);
- EEEEE: Specifies the day of the week as a narrow string (e.g. S);
- cc: Specifies the day of the week as a nominative string (e.g. Su);
- ccc: Specifies the day of the week as an abbreviated nominative string (e.g. Sun);
- cccc: Specifies the day of the week as a full nominative string (e.g. Sunday);
- ccccc: Specifies the day of the week as a narrow nominative string (e.g. S);
- H: Specifies the number of hours in 24-hour format;
- HH: Specifies the number of hours in 24-hour format with a minimum of 2 digits;
- h: Specifies the number of hours in 12-hour format;
- hh: Specifies the number of hours in 12-hour format with a minimum of 2 digits;
- a: Specifies the AM or PM hour suffix;
- m: Specifies the number of minutes;
- mm: Specifies the number of minutes with a minimum of 2 digits;
- s: Specifies the number of seconds;
- ss: Specifies the number of seconds with a minimum of 2 digits;
- S: Specifies the number of milliseconds;
- SSS: Specifies the number of milliseconds with a minimum of 3 digits.
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateTimeFullโ€‹

Formats to a localized full date/time string (for example, Wednesday, March 23, 2022 at 4:38:47 PM).

Signatureโ€‹

dateTimeFull(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized date/time string.


๐Ÿ”ง dateTimeLongโ€‹

Formats to a localized long date/time string (for example, March 23, 2022 at 4:38:38 PM).

Signatureโ€‹

dateTimeLong(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized date/time string.


๐Ÿ”ง dateTimeMediumโ€‹

Formats to a localized medium date/time string (for example, Mar 23, 2022, 4:38:29 PM).

Signatureโ€‹

dateTimeMedium(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized date/time string.


๐Ÿ”ง dateTimeShortโ€‹

Formats to a localized short date/time string (for example, 3/23/22, 4:38 PM).

Signatureโ€‹

dateTimeShort(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized date/time string.


๐Ÿ”ง findDomainโ€‹

Tries to find the most significant domain (ignoring case). This is useful to find an appropiate language code of a locale that's available (is loaded) for a certain domain. For example, if the en locale is loaded and en-US is supplied to this function, it will return en since there is no specific locale information loaded for en-US.

Signatureโ€‹

findDomain(domain: string): string

Parametersโ€‹

NameTypeOptionalDescription
domainstringNoSpecifies the ISO 639-1 language domain.

Return valueโ€‹

Returns the best matching locale domain. If nothing matches, it will return the default domain en.


๐Ÿ”ง getโ€‹

Retrieves the specified locale (or the current locale if no locale identifier is specified).

Signatureโ€‹

get(locale?: string): ILocale

Parametersโ€‹

NameTypeOptionalDescription
localestringYesSpecifies the ISO 639-1 language code to retrieve.

Return valueโ€‹

Returns the ILocale object. This method will always return a locale object. If no locales are loaded, the built-in en locale will return.


๐Ÿ”ง getDomainโ€‹

Retrieves domain information for the specified locale (or the current locale if no locale identifier is specified).

Signatureโ€‹

getDomain(locale?: string): IDomain

Parametersโ€‹

NameTypeOptionalDescription
localestringYesSpecifies the ISO 639-1 language domain.

Return valueโ€‹

Returns an IDomain object with domain info.


๐Ÿ”ง isLoadedโ€‹

Verifies if the specified locale is loaded.

Signatureโ€‹

isLoaded(locale: string): boolean

Parametersโ€‹

NameTypeOptionalDescription
localestringNoSpecifies the ISO 639-1 language code to verify.

Return valueโ€‹

Returns true if the locale is loaded.


๐Ÿ”ง loadโ€‹

Loads the specified locale profiles.

tip

Locale information is stored in a JSON file per locale and are stored in the runner/locales folder of each stock runner package.

Signatureโ€‹

load(locale: ILocale | ILocale[], makeActive?: boolean): boolean

Parametersโ€‹

NameTypeOptionalDescription
localeILocaleILocale[]No
makeActivebooleanYesSpecifies if the locale needs to be selected as the current active locale (default is true, but only when a single locale is supplied).

Return valueโ€‹

Returns true if the locale data is successfully loaded.


๐Ÿ”ง numberโ€‹

Formats a number to a localized string by inserting thousands and decimal separators while taking rounding into account.

Signatureโ€‹

number(
n: number | string,
precision?: number | "auto",
thousands?: boolean,
locale?: string
): string

Parametersโ€‹

NameTypeOptionalDescription
nnumber | stringNoSpecifies the number to format.
precisionnumber | "auto"YesSpecifies the precision (set it to auto to allow floating point numbers with automatic precision detection).
thousandsbooleanYesSpecifies if thousands separators should be inserted (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted number as a localized string.


๐Ÿ”ง setโ€‹

Sets the current active locale.

caution

Make sure to load the locale first with the locale method.

Signatureโ€‹

set(locale: string): boolean

Parametersโ€‹

NameTypeOptionalDescription
localestringNoSpecifies the ISO 639-1 language code to set.

Return valueโ€‹

Returns true if the locale is set.


๐Ÿ”ง timeFullโ€‹

Formats to a localized full time string (for example, 4:39:45 PM).

Signatureโ€‹

timeFull(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized time string.


๐Ÿ”ง timeLongโ€‹

Formats to a localized long time string (for example, 4:39:18 PM).

Signatureโ€‹

timeLong(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized time string.


๐Ÿ”ง timeMediumโ€‹

Formats to a localized medium time string (for example, 4:39:08 PM).

Signatureโ€‹

timeMedium(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized time string.


๐Ÿ”ง timeShortโ€‹

Formats to a localized short time string (for example, 4:38 PM).

Signatureโ€‹

timeShort(time?: number, UTC?: boolean, locale?: string): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).
localestringYesSpecifies the locale to use. If omitted the current active locale will be used.

Return valueโ€‹

Returns the formatted localized time string.

๐Ÿ—ƒ๏ธ Fieldsโ€‹


๐Ÿท๏ธ countryโ€‹

Retrieves the country for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ countryCodeโ€‹

Retrieves the country code for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ countryNativeโ€‹

Retrieves the native country name for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ directionโ€‹

Retrieves the text direction for the current active locale.

Typeโ€‹

"ltr" | "rtl"


๐Ÿท๏ธ domainโ€‹

Retrieves the domain for the current locale.

Typeโ€‹

string


๐Ÿท๏ธ identifierโ€‹

Retrieves the locale identifier string.

Typeโ€‹

string


๐Ÿท๏ธ languageโ€‹

Retrieves the language for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ languageNativeโ€‹

Retrieves the language in the native language for the current active locale.

Typeโ€‹

string


๐Ÿท๏ธ localeโ€‹

Retrieves the locale information for the current active locale.

Typeโ€‹

ILocale

โ–ถ๏ธ Methodsโ€‹


๐Ÿ”ง dateFullโ€‹

Formats to a localized full date string (for example, Wednesday, March 23, 2022).

Signatureโ€‹

dateFull(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateLongโ€‹

Formats to a localized long date string (for example, March 23, 2022).

Signatureโ€‹

dateLong(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateMediumโ€‹

Formats to a localized medium date string (for example, Mar 23, 2022).

Signatureโ€‹

dateMedium(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateShortโ€‹

Formats to a localized short date string (for example, 3/23/22).

Signatureโ€‹

dateShort(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateTimeโ€‹

Formats a date/time to a localized string.

Signatureโ€‹

dateTime(format: string, time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
formatstringNoSpecifies the format to use, using the CLDR date/time formatting style. The following variables are available:
- y / yyyy: Specifies the full 4-digit year;
- yy: Specifies the 2-digit year;
- M: Specifies the month number;
- MM: Specifies the month number with a minimum of 2 digits;
- MMM: Specifies the month as an abbreviated string (e.g. Jan);
- MMMM: Specifies the month as a full string (e.g. January);
- MMMMM: Specifies the month as a narrow (e.g. J);
- LLL: Specifies the month as an abbreviated nominative string (e.g. Jan);
- LLLL: Specifies the month as a full nominative string (e.g. January);
- LLLLL: Specifies the month as a narrow nominative string (e.g. J);
- d: Specifies the day of the month;
- dd: Specifies the day of the month with a minimum of 2 digits;
- E: Specifies the day of the week;
- EE: Specifies the day of the week as a string (e.g. Su);
- EEE: Specifies the day of the week as an abbreviated string (e.g. Sun);
- EEEE: Specifies the day of the week as a full string (e.g. Sunday);
- EEEEE: Specifies the day of the week as a narrow string (e.g. S);
- cc: Specifies the day of the week as a nominative string (e.g. Su);
- ccc: Specifies the day of the week as an abbreviated nominative string (e.g. Sun);
- cccc: Specifies the day of the week as a full nominative string (e.g. Sunday);
- ccccc: Specifies the day of the week as a narrow nominative string (e.g. S);
- H: Specifies the number of hours in 24-hour format;
- HH: Specifies the number of hours in 24-hour format with a minimum of 2 digits;
- h: Specifies the number of hours in 12-hour format;
- hh: Specifies the number of hours in 12-hour format with a minimum of 2 digits;
- a: Specifies the AM or PM hour suffix;
- m: Specifies the number of minutes;
- mm: Specifies the number of minutes with a minimum of 2 digits;
- s: Specifies the number of seconds;
- ss: Specifies the number of seconds with a minimum of 2 digits;
- S: Specifies the number of milliseconds;
- SSS: Specifies the number of milliseconds with a minimum of 3 digits.
timenumberYesSpecifies the date/time to format (defaults to the current date/time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized date string.


๐Ÿ”ง dateTimeFullโ€‹

Formats to a localized full date/time string (for example, Wednesday, March 23, 2022 at 4:38:47 PM).

Signatureโ€‹

dateTimeFull(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized date/time string.


๐Ÿ”ง dateTimeLongโ€‹

Formats to a localized long date/time string (for example, March 23, 2022 at 4:38:38 PM).

Signatureโ€‹

dateTimeLong(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized date/time string.


๐Ÿ”ง dateTimeMediumโ€‹

Formats to a localized medium date/time string (for example, Mar 23, 2022, 4:38:29 PM).

Signatureโ€‹

dateTimeMedium(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized date/time string.


๐Ÿ”ง dateTimeShortโ€‹

Formats to a localized short date/time string (for example, 3/23/22, 4:38 PM).

Signatureโ€‹

dateTimeShort(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized date/time string.


๐Ÿ”ง loadโ€‹

Loads the specified locale profile.

tip

Locale information is stored in a JSON file per locale and are stored in the runner/locales folder of each stock runner package.

Signatureโ€‹

load(locale: ILocale): boolean

Parametersโ€‹

NameTypeOptionalDescription
localeILocaleNoSpecifies the locale profile to load.

Return valueโ€‹

Returns true if the locale data is successfully loaded.


๐Ÿ”ง numberโ€‹

Formats a number to a localized string by inserting thousands and decimal separators while taking rounding into account.

Signatureโ€‹

number(n: number | string, precision?: number | "auto", thousands?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
nnumber | stringNoSpecifies the number to format.
precisionnumber | "auto"YesSpecifies the precision (set it to auto to allow floating point numbers with automatic precision detection).
thousandsbooleanYesSpecifies if thousands separators should be inserted (default is false).

Return valueโ€‹

Returns the formatted number as a localized string.


๐Ÿ”ง setโ€‹

Sets the current active locale for the instance.

caution

Make sure to load the locale first with the locale method.

Signatureโ€‹

set(locale: string): boolean

Parametersโ€‹

NameTypeOptionalDescription
localestringNoSpecifies the ISO 639-1 language code to set.

Return valueโ€‹

Returns true if the locale is set.


๐Ÿ”ง timeFullโ€‹

Formats to a localized full time string (for example, 4:39:45 PM).

Signatureโ€‹

timeFull(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized time string.


๐Ÿ”ง timeLongโ€‹

Formats to a localized long time string (for example, 4:39:18 PM).

Signatureโ€‹

timeLong(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized time string.


๐Ÿ”ง timeMediumโ€‹

Formats to a localized medium time string (for example, 4:39:08 PM).

Signatureโ€‹

timeMedium(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized time string.


๐Ÿ”ง timeShortโ€‹

Formats to a localized short time string (for example, 4:38 PM).

Signatureโ€‹

timeShort(time?: number, UTC?: boolean): string

Parametersโ€‹

NameTypeOptionalDescription
timenumberYesSpecifies the time to format (defaults to the current time).
UTCbooleanYesSpecifies if the UTC time needs to be used instead of local time (default is false).

Return valueโ€‹

Returns the formatted localized time string.