hs.locale
ModuleRetrieve information about the user's Language & Region settings, and respond to changes.
Locales encapsulate linguistic, cultural, and technological conventions — things like the symbol used for a decimal separator, or the way dates and calendars are formatted.
Reading locale information
console.log("Current locale: " + hs.locale.current())
const info = hs.locale.details()
console.log("Uses metric: " + info.usesMetricSystem)
Watching for changes
hs.locale.on('change', () => {
console.log("Locale settings changed: " + JSON.stringify(hs.locale.details()))
})
Properties
This module has no properties.
Methods
hs.locale.availableLocales() -> string[]
Returns the identifiers for all locales available on the system.
Declaration
hs.locale.availableLocales() -> string[]Returns
string[]
An array of locale identifier strings (e.g. `["en_US", "de_CH", "ja_JP"]`).
Example
hs.locale.availableLocales().forEach(id => console.log(id))hs.locale.current() -> string
Returns the user's currently selected locale identifier.
Declaration
hs.locale.current() -> stringReturns
string
The identifier of the user's currently selected locale (e.g. `"en_US"`).
Example
console.log("Current locale: " + hs.locale.current())hs.locale.preferredLanguages() -> string[]
Returns the user's preferred languages, in priority order.
Declaration
hs.locale.preferredLanguages() -> string[]Returns
string[]
An array of language identifier strings, most preferred first.
Example
hs.locale.preferredLanguages().forEach(l => console.log(l))hs.locale.details(identifier) -> {[key: string]: any}
Returns detailed information about the current or a specified locale.
user's currently selected locale is used.
Declaration
hs.locale.details(identifier) -> {[key: string]: any}Parameters
| Name | Type | Description |
|---|---|---|
| identifier | string | A locale identifier from `availableLocales()`. If omitted, the |
Returns
{[key: string]: any}
A dictionary describing the locale, including (where available):
Example
const info = hs.locale.details("de_CH")
console.log(info.currencySymbol + " " + info.decimalSeparator)
console.log(info.calendar.monthSymbols.join(", "))hs.locale.localizedName(localeCode, baseLocaleCode) -> [String: String]
Returns the localized display name for a locale identifier.
of the strings returned by `availableLocales()`.
currently selected locale is used. Must be one of the strings returned by
`availableLocales()`.
Declaration
hs.locale.localizedName(localeCode, baseLocaleCode) -> [String: String]Parameters
| Name | Type | Description |
|---|---|---|
| localeCode | string | The locale identifier to look up (e.g. `"de_CH"`). Must be one |
| baseLocaleCode | string | The locale to display the name in. If omitted, the user's |
Returns
[String: String]
A dictionary with `name` (e.g. `"German"`) and `nameWithDialect`
Example
const name = hs.locale.localizedName("de_CH")
console.log(name.name + " / " + name.nameWithDialect)hs.locale.on(event, listener) -> None
Register a listener that fires whenever any of the user's locale settings change.
Read `current()` or `details()` inside the listener to inspect the new state.
Declaration
hs.locale.on(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for (the only event this module emits) |
| listener | any | Called with no arguments when locale settings change |
Returns
None
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.locale.on('change', () => console.log("Locale changed to: " + hs.locale.current()))
} catch (err) {
console.error(err.message)
}hs.locale.off(event, listener) -> None
Remove a previously registered locale change listener.
Declaration
hs.locale.off(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event the listener was registered for |
| listener | any | The function originally passed to `on` |
Returns
None
Example
const onChange = () => console.log("changed")
hs.locale.on('change', onChange)
// later…
hs.locale.off('change', onChange)hs.locale.once(event, listener) -> None
Register a listener that fires at most once, the next time locale settings change.
Declaration
hs.locale.once(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for |
| listener | any | Called once, then automatically removed |
Returns
None
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.locale.once('change', () => console.log("First change detected"))
} catch (err) {
console.error(err.message)
}