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.addWatcher(() => {
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.addWatcher(listener) -> None
Registers a listener that fires whenever any of the user's locale settings change.
The listener is called with no arguments. Read `current()` or `details()` inside the
callback to inspect the new state.
The OS subscription starts lazily on the first listener and is released automatically
when the last listener is removed via `removeWatcher`.
Declaration
hs.locale.addWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | function | A function called when locale settings change. |
Returns
None
Example
hs.locale.addWatcher(() => {
console.log("Locale changed to: " + hs.locale.current())
})hs.locale.removeWatcher(listener) -> None
Removes a previously registered locale change listener.
Declaration
hs.locale.removeWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | function | The function originally passed to `addWatcher`. |
Returns
None
Example
const handler = () => console.log("changed")
hs.locale.addWatcher(handler)
hs.locale.removeWatcher(handler)