locale

​
Retrieve information about the user's Language and Region settings.
Locales encapsulate information about linguistic, cultural, and technological conventions and standards. Examples of information encapsulated by a locale include the symbol used for the decimal separator in numbers and the way dates are formatted. Locales are typically used to provide, format, and interpret information about and according to the user’s customs and preferences.
API Overview
Functions - API calls offered directly by the extension
​availableLocales​
​current​
​details​
​localizedString​
​preferredLanguages​
​registerCallback​
​unregisterCallback​
API Documentation
Functions
​availableLocales​
Signature
hs.host.locale.availableLocales() -> table
Type
Function
Description
Returns an array table containing the identifiers for the locales available on the system.
Parameters
None
Returns
an array table of strings specifying the locale identifiers recognized by this system.
Notes
these values can be used with hs.host.locale.details to get details for a specific locale.
​current​
Signature
hs.host.locale.current() -> string
Type
Function
Description
Returns an string specifying the user's currently selected locale identifier.
Parameters
None
Returns
a string specifying the identifier of the user's currently selected locale.
Notes
this value can be used with hs.host.locale.details to get details for the returned locale.
​details​
Signature
hs.host.locale.details([identifier]) -> table
Type
Function
Description
Returns a table containing information about the current or specified locale.
Parameters
identifier - an optional string, specifying the locale to display information about. If you do not specify an identifier, information about the user's currently selected locale is returned.
Returns
a table containing one or more of the following key-value pairs:
alternateQuotationBeginDelimiterKey - A string containing the alternating begin quotation symbol associated with the locale. In some locales, when quotations are nested, the quotation characters alternate.
alternateQuotationEndDelimiterKey - A string containing the alternate end quotation symbol associated with the locale. In some locales, when quotations are nested, the quotation characters alternate.
calendar - A table containing key-value pairs describing for calendar associated with the locale. The table will contain one or more of the following pairs:
AMSymbol - The AM symbol for time in the locale's calendar.
calendarIdentifier - A string representing the calendar identity.
eraSymbols - An array table of strings specifying the names of the eras as recognized in the locale's calendar.
firstWeekday - The index in weekdaySymbols of the first weekday in the locale's calendar.
longEraSymbols - An array table of strings specifying long names of the eras as recognized in the locale's calendar.
minimumDaysInFirstWeek - The minimum number of days, an integer value, in the first week in the locale's calendar.
monthSymbols - An array table of strings for the months of the year in the locale's calendar.
PMSymbol - The PM symbol for time in the locale's calendar.
quarterSymbols - An array table of strings for the quarters of the year in the locale's calendar.
shortMonthSymbols - An array table of short strings for the months of the year in the locale's calendar.
shortQuarterSymbols - An array table of short strings for the quarters of the year in the locale's calendar.
shortStandaloneMonthSymbols - An array table of short standalone strings for the months of the year in the locale's calendar.
shortStandaloneQuarterSymbols - An array table of short standalone strings for the quarters of the year in the locale's calendar.
shortStandaloneWeekdaySymbols - An array table of short standalone strings for the days of the week in the locale's calendar.
shortWeekdaySymbols - An array table of short strings for the days of the week in the locale's calendar.
standaloneMonthSymbols - An array table of standalone strings for the months of the year in the locale's calendar.
standaloneQuarterSymbols - An array table of standalone strings for the quarters of the year in the locale's calendar.
standaloneWeekdaySymbols - An array table of standalone strings for the days of the week in the locale's calendar.
veryShortMonthSymbols - An array table of very short strings for the months of the year in the locale's calendar.
veryShortStandaloneMonthSymbols - An array table of very short standalone strings for the months of the year in the locale's calendar.
veryShortStandaloneWeekdaySymbols - An array table of very short standalone strings for the days of the week in the locale's calendar.
veryShortWeekdaySymbols - An array table of very short strings for the days of the week in the locale's calendar.
weekdaySymbols - An array table of strings for the days of the week in the locale's calendar.
collationIdentifier - A string containing the collation associated with the locale.
collatorIdentifier - A string containing the collation identifier for the locale.
countryCode - A string containing the locale country code.
currencyCode - A string containing the currency code associated with the locale.
currencySymbol - A string containing the currency symbol associated with the locale.
decimalSeparator - A string containing the decimal separator associated with the locale.
exemplarCharacterSet - An array table of strings which make up the exemplar character set for the locale.
groupingSeparator - A string containing the numeric grouping separator associated with the locale.
identifier - A string containing the locale identifier.
languageCode - A string containing the locale language code.
measurementSystem - A string containing the measurement system associated with the locale.
quotationBeginDelimiterKey - A string containing the begin quotation symbol associated with the locale.
quotationEndDelimiterKey - A string containing the end quotation symbol associated with the locale.
scriptCode - A string containing the locale script code.
temperatureUnit - A string containing the preferred measurement system for temperature.
timeFormatIs24Hour - A boolean specifying whether time is expressed in a 24 hour format (true) or 12 hour format (false).
usesMetricSystem - A boolean specifying whether or not the locale uses the metric system.
variantCode - A string containing the locale variant code.
Notes
If you specify a locale identifier as an argument, it should be based on one of the strings returned by hs.host.locale.availableLocales. Use of an arbitrary string may produce unreliable or inconsistent results.
​localizedString​
| Signature | hs.host.locale.localizedString(localeCode[, baseLocaleCode]) -> string | nil, string | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Returns the localized string for a specific language code. | | Parameters |
localeCode - The locale code for the locale you want to return the localized string of.
baseLocaleCode - An optional string, specifying the locale to use for the string. If you do not specify a baseLocaleCode, the user's currently selected locale is used.
| | Returns |
A string containing the localized string or nil if either the localeCode or baseLocaleCode is invalid. For example, if the localeCode is "de_CH", this will return "German".
A string containing the localized string including the dialect or nil if either the localeCode or baseLocaleCode is invalid. For example, if the localeCode is "de_CH", this will return "German (Switzerland)".
| | Notes |
The localeCode and optional baseLocaleCode must be one of the strings returned by hs.host.locale.availableLocales.
|
​preferredLanguages​
Signature
hs.host.locale.preferredLanguages() -> table
Type
Function
Description
Returns the user's language preference order as an array of strings.
Parameters
None
Returns
an array table of strings specifying the user's preferred languages as string identifiers.
​registerCallback​
Signature
hs.host.locale.registerCallback(function) -> uuidString
Type
Function
Description
Registers a function to be invoked when anything in the user's locale settings change
Parameters
fn - the function to be invoked when a setting changes
Returns
a uuid string which can be used to unregister a callback function when you no longer require notification of changes
Notes
The callback function will not receive any arguments and should return none. You can retrieve the new locale settings with hs.host.locale.localeInformation and check its keys to determine if the change is of interest.
​unregisterCallback​
Signature
hs.host.locale.unregisterCallback(uuidString) -> boolean
Type
Function
Description
Unregister a callback function when you no longer care about changes to the user's locale
Parameters
uuidString - the uuidString returned by hs.host.locale.registerCallback when you registered the callback function
Returns
true if the callback was successfully unregistered or false if it was not, usually because the uuidString does not correspond to a current callback function.

Last modified 1yr ago

Signature	`hs.host.locale.availableLocales() -> table`
Type	Function
Description	Returns an array table containing the identifiers for the locales available on the system.
Parameters	None
Returns	an array table of strings specifying the locale identifiers recognized by this system.
Notes	these values can be used with hs.host.locale.details to get details for a specific locale.

Signature	`hs.host.locale.current() -> string`
Type	Function
Description	Returns an string specifying the user's currently selected locale identifier.
Parameters	None
Returns	a string specifying the identifier of the user's currently selected locale.
Notes	this value can be used with hs.host.locale.details to get details for the returned locale.

Signature	`hs.host.locale.details([identifier]) -> table`
Type	Function
Description	Returns a table containing information about the current or specified locale.
Parameters	`identifier` - an optional string, specifying the locale to display information about. If you do not specify an identifier, information about the user's currently selected locale is returned.
Returns	a table containing one or more of the following key-value pairs: `alternateQuotationBeginDelimiterKey` - A string containing the alternating begin quotation symbol associated with the locale. In some locales, when quotations are nested, the quotation characters alternate. `alternateQuotationEndDelimiterKey` - A string containing the alternate end quotation symbol associated with the locale. In some locales, when quotations are nested, the quotation characters alternate. `calendar` - A table containing key-value pairs describing for calendar associated with the locale. The table will contain one or more of the following pairs: `AMSymbol` - The AM symbol for time in the locale's calendar. `calendarIdentifier` - A string representing the calendar identity. `eraSymbols` - An array table of strings specifying the names of the eras as recognized in the locale's calendar. `firstWeekday` - The index in `weekdaySymbols` of the first weekday in the locale's calendar. `longEraSymbols` - An array table of strings specifying long names of the eras as recognized in the locale's calendar. `minimumDaysInFirstWeek` - The minimum number of days, an integer value, in the first week in the locale's calendar. `monthSymbols` - An array table of strings for the months of the year in the locale's calendar. `PMSymbol` - The PM symbol for time in the locale's calendar. `quarterSymbols` - An array table of strings for the quarters of the year in the locale's calendar. `shortMonthSymbols` - An array table of short strings for the months of the year in the locale's calendar. `shortQuarterSymbols` - An array table of short strings for the quarters of the year in the locale's calendar. `shortStandaloneMonthSymbols` - An array table of short standalone strings for the months of the year in the locale's calendar. `shortStandaloneQuarterSymbols` - An array table of short standalone strings for the quarters of the year in the locale's calendar. `shortStandaloneWeekdaySymbols` - An array table of short standalone strings for the days of the week in the locale's calendar. `shortWeekdaySymbols` - An array table of short strings for the days of the week in the locale's calendar. `standaloneMonthSymbols` - An array table of standalone strings for the months of the year in the locale's calendar. `standaloneQuarterSymbols` - An array table of standalone strings for the quarters of the year in the locale's calendar. `standaloneWeekdaySymbols` - An array table of standalone strings for the days of the week in the locale's calendar. `veryShortMonthSymbols` - An array table of very short strings for the months of the year in the locale's calendar. `veryShortStandaloneMonthSymbols` - An array table of very short standalone strings for the months of the year in the locale's calendar. `veryShortStandaloneWeekdaySymbols` - An array table of very short standalone strings for the days of the week in the locale's calendar. `veryShortWeekdaySymbols` - An array table of very short strings for the days of the week in the locale's calendar. `weekdaySymbols` - An array table of strings for the days of the week in the locale's calendar. `collationIdentifier` - A string containing the collation associated with the locale. `collatorIdentifier` - A string containing the collation identifier for the locale. `countryCode` - A string containing the locale country code. `currencyCode` - A string containing the currency code associated with the locale. `currencySymbol` - A string containing the currency symbol associated with the locale. `decimalSeparator` - A string containing the decimal separator associated with the locale. `exemplarCharacterSet` - An array table of strings which make up the exemplar character set for the locale. `groupingSeparator` - A string containing the numeric grouping separator associated with the locale. `identifier` - A string containing the locale identifier. `languageCode` - A string containing the locale language code. `measurementSystem` - A string containing the measurement system associated with the locale. `quotationBeginDelimiterKey` - A string containing the begin quotation symbol associated with the locale. `quotationEndDelimiterKey` - A string containing the end quotation symbol associated with the locale. `scriptCode` - A string containing the locale script code. `temperatureUnit` - A string containing the preferred measurement system for temperature. `timeFormatIs24Hour` - A boolean specifying whether time is expressed in a 24 hour format (true) or 12 hour format (false). `usesMetricSystem` - A boolean specifying whether or not the locale uses the metric system. `variantCode` - A string containing the locale variant code.
Notes	If you specify a locale identifier as an argument, it should be based on one of the strings returned by hs.host.locale.availableLocales. Use of an arbitrary string may produce unreliable or inconsistent results.

Signature	`hs.host.locale.preferredLanguages() -> table`
Type	Function
Description	Returns the user's language preference order as an array of strings.
Parameters	None
Returns	an array table of strings specifying the user's preferred languages as string identifiers.

Signature	`hs.host.locale.registerCallback(function) -> uuidString`
Type	Function
Description	Registers a function to be invoked when anything in the user's locale settings change
Parameters	`fn` - the function to be invoked when a setting changes
Returns	a uuid string which can be used to unregister a callback function when you no longer require notification of changes
Notes	The callback function will not receive any arguments and should return none. You can retrieve the new locale settings with hs.host.locale.localeInformation and check its keys to determine if the change is of interest.

Signature	`hs.host.locale.unregisterCallback(uuidString) -> boolean`
Type	Function
Description	Unregister a callback function when you no longer care about changes to the user's locale
Parameters	`uuidString` - the uuidString returned by hs.host.locale.registerCallback when you registered the callback function
Returns	true if the callback was successfully unregistered or false if it was not, usually because the uuidString does not correspond to a current callback function.

locale

API Overview

API Documentation

Functions

​availableLocales​

​current​

​details​

​localizedString​

​preferredLanguages​

​registerCallback​

​unregisterCallback​

availableLocales

current

details

localizedString

preferredLanguages

registerCallback

unregisterCallback