Skip to main content

ResolveLocaleUtils

Shared locale-id parsing and resolution. Keeps the "given a locale like en-us, what do we actually use?" logic in one place so number formatting, dialog pacing, and any other locale-sensitive feature resolve identically.

Locale ids follow BCP-47-ish shapes: a language subtag, then optional script and/or region subtags separated by - (or sometimes _), e.g. en, en-us, pt-br, zh-Hant-TW. Matching is case-insensitive.

Functions​

getLanguageSubtag​

</>
ResolveLocaleUtils.getLanguageSubtag(locale: string?) → string?

Returns the lowercased primary language subtag, or nil when the input has no language subtag (nil, non-string, empty, or leading punctuation/digits). 

ResolveLocaleUtils.getLanguageSubtag("en-us") --> "en"
ResolveLocaleUtils.getLanguageSubtag("zh_Hant_TW") --> "zh"
ResolveLocaleUtils.getLanguageSubtag("PT-BR") --> "pt"
ResolveLocaleUtils.getLanguageSubtag(nil) --> nil

getScriptSubtag​

</>
ResolveLocaleUtils.getScriptSubtag(locale: string?) → string?

Returns the script subtag, or nil when the locale does not carry one. A script subtag is the four-letter subtag directly after the language (zh-Hant, zh-Hant-TW, sr-Latn); a two-letter or three-digit subtag in that position is a region, not a script. 

ResolveLocaleUtils.getScriptSubtag("zh-Hant-TW") --> "hant"
ResolveLocaleUtils.getScriptSubtag("zh-TW") --> nil

isTraditionalChinese​

</>
ResolveLocaleUtils.isTraditionalChinese(locale: string?) → boolean

Whether a Chinese locale is Traditional. The hant script subtag, and the tw / hk / mo regions, are Traditional; everything else (hans, cn, sg, bare zh) is Simplified. Only meaningful for zh locales.

isCompatibleLocale​

</>
ResolveLocaleUtils.isCompatibleLocale(
locale: string?,
otherLocale: string?
) → boolean

Whether two locales are close enough that one can be read in place of the other: the same language, written in the same script.

Regional variants of a language substitute for one another, so es-mx reads es-es and en-gb reads en-us. Scripts do not: Traditional and Simplified Chinese are not mutually readable, so zh-tw never reads zh-cn, whether the script is spelled out (zh-Hant vs zh-Hans) or implied by region (zh-tw vs zh-cn). The same holds for any language whose locales carry differing script subtags, such as sr-Latn and sr-Cyrl. 

ResolveLocaleUtils.isCompatibleLocale("es-mx", "es-es") --> true
ResolveLocaleUtils.isCompatibleLocale("zh-tw", "zh-cn") --> false
ResolveLocaleUtils.isCompatibleLocale("pt-br", "en-us") --> false

resolveClosestKey​

</>
ResolveLocaleUtils.resolveClosestKey(
locale: string?,
availableLocales: {[string]: T}
) → string?

Resolves a locale to the best-matching key present in availableLocales:

  1. Exact (case-insensitive) match.
  2. Chinese Traditional/Simplified routing to whichever variant keys exist.
  3. Closest key sharing the language subtag (smallest key, so the pick is deterministic), so e.g. en-gb falls back to en-us and es-mx to es-es rather than to an unrelated default.

Returns nil when nothing shares the language subtag; callers apply their own default in that case.

Show raw api
{
    "functions": [
        {
            "name": "getLanguageSubtag",
            "desc": "Returns the lowercased primary language subtag, or nil when the input has no\nlanguage subtag (nil, non-string, empty, or leading punctuation/digits).\n\n```lua\nResolveLocaleUtils.getLanguageSubtag(\"en-us\") --> \"en\"\nResolveLocaleUtils.getLanguageSubtag(\"zh_Hant_TW\") --> \"zh\"\nResolveLocaleUtils.getLanguageSubtag(\"PT-BR\") --> \"pt\"\nResolveLocaleUtils.getLanguageSubtag(nil) --> nil\n```",
            "params": [
                {
                    "name": "locale",
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 40,
                "path": "src/clienttranslator/src/Shared/Utils/ResolveLocaleUtils.lua"
            }
        },
        {
            "name": "getScriptSubtag",
            "desc": "Returns the script subtag, or nil when the locale does not carry one. A script subtag is\nthe four-letter subtag directly after the language (`zh-Hant`, `zh-Hant-TW`, `sr-Latn`);\na two-letter or three-digit subtag in that position is a region, not a script.\n\n```lua\nResolveLocaleUtils.getScriptSubtag(\"zh-Hant-TW\") --> \"hant\"\nResolveLocaleUtils.getScriptSubtag(\"zh-TW\") --> nil\n```",
            "params": [
                {
                    "name": "locale",
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 95,
                "path": "src/clienttranslator/src/Shared/Utils/ResolveLocaleUtils.lua"
            }
        },
        {
            "name": "isTraditionalChinese",
            "desc": "Whether a Chinese locale is Traditional. The `hant` script subtag, and the `tw` / `hk` /\n`mo` regions, are Traditional; everything else (`hans`, `cn`, `sg`, bare `zh`) is\nSimplified. Only meaningful for `zh` locales.",
            "params": [
                {
                    "name": "locale",
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 118,
                "path": "src/clienttranslator/src/Shared/Utils/ResolveLocaleUtils.lua"
            }
        },
        {
            "name": "isCompatibleLocale",
            "desc": "Whether two locales are close enough that one can be read in place of the other: the same\nlanguage, written in the same script.\n\nRegional variants of a language substitute for one another, so `es-mx` reads `es-es` and\n`en-gb` reads `en-us`. Scripts do not: Traditional and Simplified Chinese are not mutually\nreadable, so `zh-tw` never reads `zh-cn`, whether the script is spelled out (`zh-Hant` vs\n`zh-Hans`) or implied by region (`zh-tw` vs `zh-cn`). The same holds for any language\nwhose locales carry differing script subtags, such as `sr-Latn` and `sr-Cyrl`.\n\n```lua\nResolveLocaleUtils.isCompatibleLocale(\"es-mx\", \"es-es\") --> true\nResolveLocaleUtils.isCompatibleLocale(\"zh-tw\", \"zh-cn\") --> false\nResolveLocaleUtils.isCompatibleLocale(\"pt-br\", \"en-us\") --> false\n```",
            "params": [
                {
                    "name": "locale",
                    "desc": "",
                    "lua_type": "string?"
                },
                {
                    "name": "otherLocale",
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 161,
                "path": "src/clienttranslator/src/Shared/Utils/ResolveLocaleUtils.lua"
            }
        },
        {
            "name": "resolveClosestKey",
            "desc": "Resolves a locale to the best-matching key present in `availableLocales`:\n\n1. Exact (case-insensitive) match.\n2. Chinese Traditional/Simplified routing to whichever variant keys exist.\n3. Closest key sharing the language subtag (smallest key, so the pick is\n   deterministic), so e.g. `en-gb` falls back to `en-us` and `es-mx` to `es-es`\n   rather than to an unrelated default.\n\nReturns nil when nothing shares the language subtag; callers apply their own\ndefault in that case.",
            "params": [
                {
                    "name": "locale",
                    "desc": "",
                    "lua_type": "string?"
                },
                {
                    "name": "availableLocales",
                    "desc": "",
                    "lua_type": "{ [string]: T }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 203,
                "path": "src/clienttranslator/src/Shared/Utils/ResolveLocaleUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "ResolveLocaleUtils",
    "desc": "Shared locale-id parsing and resolution. Keeps the \"given a locale like\n`en-us`, what do we actually use?\" logic in one place so number formatting,\ndialog pacing, and any other locale-sensitive feature resolve identically.\n\nLocale ids follow BCP-47-ish shapes: a language subtag, then optional script\nand/or region subtags separated by `-` (or sometimes `_`), e.g. `en`, `en-us`,\n`pt-br`, `zh-Hant-TW`. Matching is case-insensitive.",
    "source": {
        "line": 13,
        "path": "src/clienttranslator/src/Shared/Utils/ResolveLocaleUtils.lua"
    }
}