#cp.i18n.localeID

As per Apple's documentation, a locale ID is a code which identifies either a language used across multiple regions, a dialect from a specific region, a script used in multiple regions, or a combination of all three. See the parse function for details.

When you parse a code with the forCode function, it will result in a table that contains a reference to the approprate cp.i18n.language table, and any specified cp.i18n.region or cp.i18n.script tables. These contain the full details for each language/regin/script, as appropriate.

You can also convert the resulting table back to the code via tostring, or the code method.


#API Overview

Functions - API calls offered directly by the extension

Constructors - API calls which return an object, typically one that offers API methods

Fields - Variables which can only be accessed from an object returned by a constructor

Methods - API calls which can only be made on an object returned by a constructor


#API Documentation

#Functions

Signaturecp.i18n.localeID.is(other) -> boolean
TypeFunction
DescriptionChecks if the other is a localeID.
Parameters
  • other - the other value to check.
Returns
  • true if it is a cp.i18n.locale, otherwise false.
NotesNone
ExamplesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 36

Signaturecp.i18n.localeID.parse(code) -> string, string, string
TypeFunction
DescriptionThis function will first attempt to determine the language, script and region by using hs.host.locale.details(). If that fails, it will use Lua patterns as described below.
Parameters
  • code - The locale ID code. Eg. "en_AU".
Returns
  • language - The two-character lower-case alpha language code.
  • region - The two-character upper-case alpha region code.
  • script - the four-character mixed-case alpha script code.
Notes
  • This function will first attempt to determine the language, script and region by using hs.host.locale.details(). If that fails, it will use Lua patterns as described below.
  • Parses a language ID into three possible string components:
  • ** The ISO 693-1 language code
  • ** The ISO 15924 script code
  • ** The ISO 3166-1 region code
  • This is one of the following patterns:
  • ** [language] - eg. "en", or "fr". This covers the language across all languages and scripts. We also allow the full name (eg. "English" or "French") since this seems common in Apple's I18N management.
  • ** [language]_[region] - eg. "en_AU" for Australian English, "fr_CA" for Canadian French, etc.
  • ** [language]-[script] - eg. "az-Arab" for Azerbaijani in Arabic script, "az-Latn" for Azerbaijani in Latin script.
  • ** [language]-[script]_[region] - eg. "en-Latin-AU"
  • It will then return the matched component in three return values: language, script, region.
  • If a region is specified, the script will be nil. Eg.:
  • lua</li><li>local lang, scrpt, rgn = localeID.parse("en_AU") -- results in "en", nil, "AU"</li><li>
ExamplesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 49

#Constructors

Signaturecp.i18n.localeID.forCode(code) -> cp.i18n.localeID or nil
TypeConstructor
DescriptionCreates, or retrieves from the cache, a localeID instance for the specified code.
Parameters
  • code - The language ID code.
Returns
  • The matching langaugeID, or nil.
Notes
  • If the code can't be parsed, or if the actual language/region/script codes don't exist, nil is returned.
ExamplesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 105

#Fields

Signaturecp.i18n.localeID.code <string>
TypeField
DescriptionThe locale ID code.
NotesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 240

Signaturecp.i18n.localeID.language <cp.i18n.language>
TypeField
DescriptionThe matching language details.
NotesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 252

Signaturecp.i18n.localeID.localName <string>
TypeField
DescriptionThe local name in it's own language.
NotesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 248

Signaturecp.i18n.localeID.name <string>
TypeField
DescriptionThe locale name in English.
NotesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 244

Signaturecp.i18n.localeID.region <cp.i18n.region>
TypeField
DescriptionThe matching region details, if appropriate. Will be nil if no region was specified in the code.
NotesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 256

Signaturecp.i18n.localeID.script <cp.i18n.script>
TypeField
DescriptionThe matching script details, if appropriate. Will be nil if no script was specified in the code.
NotesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 260

#Methods

Signaturecp.i18n.localeID:matches(otherLocale) -> number
TypeMethod
DescriptionThis compares the otherLocale to this locale and returns a number indicating the 'strength' of the match.
Parameters
  • otherLocale - The other locale to compare to.
Returns
  • A number from 0 to 3 indicating the match strength.
Notes
  • It will be a value between 0 and 3. The script and region in any locale are optional, and if they are not provided, they are considered "open" and will match with another locale which has the script or region defined. However, it is considered to be a weaker match.
  • For example:
  • lua</li><li>local l = localeID.forCode</li><li>local en, en_AU, en_Latn, en_Latn_AU, en_NZ, de = l("en"), l("en_AU"), l("en-Latn"), l("en-Latn_AU"), l("en_NZ"), l("de")</li><li></li><li>en:matches(de) == 0 -- no match - different language</li><li></li><li>en:matches(en) == 3 -- language, script, and region match exactly</li><li>en:matches(en_AU) == 2.5 -- language and script match, region half-match with one side "open".</li><li>en:matches(en_Latn) == 2.5 -- language and region match, script half-match with one side "open".</li><li>en:matches(en_Latn_AU) == 2 -- language matches, two half-matches for script and region.</li><li></li><li>en_AU:matches(en_AU) == 3 -- exact match</li><li>en_AU:matches(en) == 2.5 -- language and script match, region half-match with a `nil` on one side.</li><li>en_AU:matches(en_NZ) == 2 -- language and script match, but no match between specific regions.</li><li>en_AU:matches(en_Latn_AU) == 2.5 -- language and region match exactly, and the optional `script` value is different.</li><li>
  • The higher the match value, the closer they are to matching. If selecting a from multiple locales which match you will generally want the highest-ranking match.
ExamplesNone
Sourcesrc/extensions/cp/i18n/localeID.lua line 187