# Released under the MIT License. See LICENSE for details.
#
"""Functionality for wrangling locale info."""
from __future__ import annotations # Docs-generation hack.
# Length here is exhaustive per-locale data, not accumulated cruft: six
# properties each if-chain over all ~44 values so assert_never() makes a
# missed locale a type error. Those chains have to sit next to the enum
# to do that, so splitting them out would trade the guarantee for a line
# count.
# pylint: disable=too-many-lines
import logging
import unicodedata
from enum import Enum
from functools import cached_property, lru_cache
from typing import TYPE_CHECKING, assert_never, assert_type
if TYPE_CHECKING:
pass
#: Separator between a language picker entry's two halves.
#:
#: **This is a workaround for an engine text-layout quirk, and the exact
#: character matters. Do not "clean this up" to an em dash.**
#:
#: The game client absorbs punctuation into an adjacent OS-rendered text
#: span on purpose, so punctuation next to OS-drawn glyphs doesn't
#: visually mismatch it (``TextGraphics::IsOSDrawableAscii``, whose
#: comment says as much). The layout loop is roughly::
#:
#: if (IsOSDrawableAscii(val) && !os_span.empty()) {
#: os_span.push_back(val); // absorbed
#: } else if (Glyph* g = GetGlyph(val, big)) {
#: ... // baked glyph; CLOSES the span
#: } else {
#: os_span.push_back(val); // no glyph -> absorbed anyway
#: }
#:
#: An RTL endonym opens an OS span. A separator that gets absorbed joins
#: that span, so bidi runs over "<arabic> - " as one unit, resolves the
#: trailing neutrals against an RTL paragraph, and draws them on the
#: *left*: ``- العربية Arabic``. A separator that instead closes the span
#: leaves the Arabic alone in it, where it shapes correctly.
#:
#: U+00B7 MIDDLE DOT closes it because it clears **both** gates, and each
#: is independently required:
#:
#: 1. It is above every ASCII range ``IsOSDrawableAscii`` tests
#: (32-47, 58-64, 91-96, 123-126), so it is not absorbed. An ASCII
#: hyphen (45) sits in the first range and IS absorbed -- which is why
#: swapping the em dash for a hyphen changed nothing.
#: 2. It is under ``kGlyphCount`` (1280) and ``g_glyph_map[183]`` is a
#: real font page, so it has a baked glyph and takes the span-closing
#: branch.
#:
#: Miss either and it breaks: an em dash (U+2014) clears gate 1 but is
#: above 1280, so it has no baked glyph, falls to the final ``else``, and
#: is absorbed regardless. Same for a bullet (U+2022). **So the rule is
#: NOT "use any non-ASCII character"** -- it is "128-1279 with a baked
#: glyph", or one of the ASCII characters ``IsOSDrawableAscii``
#: explicitly excludes (parens, quotes, brackets).
#:
#: Parentheses would work too and were the original form, but they nest
#: badly: the qualified variants already carry their own parenthetical on
#: both sides, giving ``Português (Brasil) (Portuguese (Brazil))``.
#:
#: Verified on Android 2026-07-30. That generalizes across platforms in a
#: way the earlier bidi-isolate attempt did not: this hinges on the baked
#: font sheet and on platform-independent engine code, not on each
#: platform's text stack. Full trace, including two failed approaches, in
#: ballistica-internal ``docs/followups.md``.
LANGUAGE_PICKER_SEPARATOR = '\u00b7' # MIDDLE DOT
[docs]
def language_picker_label(locale: LocaleResolved, translated_name: str) -> str:
"""Build one entry for a language picker.
Reads ``"<endonym> · <name in the reader's language>"``, e.g.
``"Svenska · Swedish"``, collapsing to just the endonym when the two
would be identical (the entry for the language you already use).
The endonym lets a speaker find their own language whatever the ui
is set to; the translated name lets everyone else identify a script
they cannot read. Shape follows macOS's language list, which uses a
dash; see :data:`LANGUAGE_PICKER_SEPARATOR` for why we cannot.
Known remaining wart, engine-side: the space *before* the separator
still gets absorbed into an RTL endonym's span, so those rows render
slightly tight on that side (``العربية· Arabic``). And when *both*
halves are non-ASCII -- an RTL endonym in a CJK ui -- everything
lands in one span whatever the separator, and one of the two orders
always reverses. That one needs real mixed-direction layout in the
engine (docs/followups.md). The master server's html picker is
unaffected throughout: the browser lays out the whole string itself.
Lives beside the data rather than in either picker because there
are two of them -- the client's settings window and the master
server's account-settings page -- and they have already drifted
once on ordering.
"""
if locale.endonym == translated_name:
return locale.endonym
return f'{locale.endonym} {LANGUAGE_PICKER_SEPARATOR} {translated_name}'
[docs]
class Locale(Enum):
"""A distinct grouping of language, cultural norms, etc.
This list of locales is considered 'sacred' - we assume any values
(and associated long values) added here remain in use out in the
wild indefinitely. If a locale is superseded by a newer or more
specific one, the new locale should be added and both new and old
should map to the same :class:`LocaleResolved`.
"""
# Locale values are not iso codes or anything specific; just
# abbreviated English strings intended to be recognizable. In cases
# where space is unimportant or humans might be writing these, go
# with long-values which .
ENGLISH = 'eng'
CHINESE = 'chn' # Obsolete
CHINESE_TRADITIONAL = 'chn_tr'
CHINESE_SIMPLIFIED = 'chn_sim'
PORTUGUESE = 'prtg' # Obsolete
PORTUGUESE_PORTUGAL = 'prtg_pr'
PORTUGUESE_BRAZIL = 'prtg_brz'
ARABIC = 'arabc'
BELARUSSIAN = 'blrs'
CROATIAN = 'croat'
CZECH = 'czch'
DANISH = 'dnsh'
DUTCH = 'dtch'
PIRATE_SPEAK = 'pirate'
ESPERANTO = 'esprnto'
FILIPINO = 'filp'
FRENCH = 'frnch'
GERMAN = 'grmn'
GIBBERISH = 'gibber'
GREEK = 'greek'
HINDI = 'hndi'
HUNGARIAN = 'hngr'
INDONESIAN = 'indnsn'
ITALIAN = 'italn'
KOREAN = 'kor'
MALAY = 'mlay'
PERSIAN = 'pers'
POLISH = 'pol'
ROMANIAN = 'rom'
RUSSIAN = 'rusn'
SERBIAN = 'srbn'
SPANISH = 'spn' # Obsolete
SPANISH_LATIN_AMERICA = 'spn_lat'
SPANISH_SPAIN = 'spn_spn'
SLOVAK = 'slvk'
SWEDISH = 'swed'
TAMIL = 'taml'
THAI = 'thai'
TURKISH = 'turk'
UKRAINIAN = 'ukrn'
VENETIAN = 'venetn'
VIETNAMESE = 'viet'
KAZAKH = 'kazk'
JAPANESE = 'jpn'
# Note: We use if-statement chains here so we can use assert_never()
# to ensure we cover all existing values. But we cache lookups so
# that we only have to go through those long if-statement chains
# once per enum value.
[docs]
@cached_property
def long_value(self) -> str:
"""A longer more human readable alternative to value.
Like the regular enum values, these values will never change and
can be used for persistent storage/etc.
"""
# pylint: disable=too-many-branches
# pylint: disable=too-many-return-statements
cls = Locale
if self is cls.ENGLISH:
return 'English'
if self is cls.CHINESE:
return 'Chinese'
if self is cls.CHINESE_TRADITIONAL:
return 'ChineseTraditional'
if self is cls.CHINESE_SIMPLIFIED:
return 'ChineseSimplified'
if self is cls.PORTUGUESE:
return 'Portuguese'
if self is cls.PORTUGUESE_PORTUGAL:
return 'PortuguesePortugal'
if self is cls.PORTUGUESE_BRAZIL:
return 'PortugueseBrazil'
if self is cls.ARABIC:
return 'Arabic'
if self is cls.BELARUSSIAN:
return 'Belarussian'
if self is cls.CROATIAN:
return 'Croatian'
if self is cls.CZECH:
return 'Czech'
if self is cls.DANISH:
return 'Danish'
if self is cls.DUTCH:
return 'Dutch'
if self is cls.PIRATE_SPEAK:
return 'PirateSpeak'
if self is cls.ESPERANTO:
return 'Esperanto'
if self is cls.FILIPINO:
return 'Filipino'
if self is cls.FRENCH:
return 'French'
if self is cls.GERMAN:
return 'German'
if self is cls.GIBBERISH:
return 'Gibberish'
if self is cls.GREEK:
return 'Greek'
if self is cls.HINDI:
return 'Hindi'
if self is cls.HUNGARIAN:
return 'Hungarian'
if self is cls.INDONESIAN:
return 'Indonesian'
if self is cls.ITALIAN:
return 'Italian'
if self is cls.KOREAN:
return 'Korean'
if self is cls.MALAY:
return 'Malay'
if self is cls.PERSIAN:
return 'Persian'
if self is cls.POLISH:
return 'Polish'
if self is cls.ROMANIAN:
return 'Romanian'
if self is cls.RUSSIAN:
return 'Russian'
if self is cls.SERBIAN:
return 'Serbian'
if self is cls.SPANISH:
return 'Spanish'
if self is cls.SPANISH_LATIN_AMERICA:
return 'SpanishLatinAmerica'
if self is cls.SPANISH_SPAIN:
return 'SpanishSpain'
if self is cls.SLOVAK:
return 'Slovak'
if self is cls.SWEDISH:
return 'Swedish'
if self is cls.TAMIL:
return 'Tamil'
if self is cls.THAI:
return 'Thai'
if self is cls.TURKISH:
return 'Turkish'
if self is cls.UKRAINIAN:
return 'Ukrainian'
if self is cls.VENETIAN:
return 'Venetian'
if self is cls.VIETNAMESE:
return 'Vietnamese'
if self is cls.KAZAKH:
return 'Kazakh'
if self is cls.JAPANESE:
return 'Japanese'
# Make sure we've covered all cases.
assert_never(self)
[docs]
@classmethod
def from_long_value(cls, value: str) -> Locale:
"""Given a long value, return a Locale."""
# Build a map of long-values to locales on demand.
storekey = '_from_long_value'
fromvals: dict[str, Locale] | None = getattr(cls, storekey, None)
if fromvals is None:
fromvals = {val.long_value: val for val in cls}
setattr(cls, storekey, fromvals)
try:
return fromvals[value]
except KeyError as exc:
raise ValueError(f'Invalid long value "{value}"') from exc
[docs]
@cached_property
def description(self) -> str:
"""A human readable description for the locale.
Intended as instructions to humans or AI for translating. For
most locales this is simply the language name, but for special
ones like pirate-speak it may include instructions.
"""
# pylint: disable=too-many-branches
# pylint: disable=too-many-return-statements
cls = Locale
if self is cls.ENGLISH:
return 'English'
if self is cls.CHINESE:
return 'Chinese'
if self is cls.CHINESE_TRADITIONAL:
return 'Chinese (Traditional)'
if self is cls.CHINESE_SIMPLIFIED:
return 'Chinese (Simplified)'
if self is cls.PORTUGUESE:
return 'Portuguese'
if self is cls.PORTUGUESE_PORTUGAL:
return 'Portuguese (Portugal)'
if self is cls.PORTUGUESE_BRAZIL:
return 'Portuguese (Brazil)'
if self is cls.ARABIC:
return 'Arabic'
if self is cls.BELARUSSIAN:
return 'Belarussian'
if self is cls.CROATIAN:
return 'Croatian'
if self is cls.CZECH:
return 'Czech'
if self is cls.DANISH:
return 'Danish'
if self is cls.DUTCH:
return 'Dutch'
if self is cls.PIRATE_SPEAK:
return 'Pirate-Speak (English as spoken by a pirate)'
if self is cls.ESPERANTO:
return 'Esperanto'
if self is cls.FILIPINO:
return 'Filipino'
if self is cls.FRENCH:
return 'French'
if self is cls.GERMAN:
return 'German'
if self is cls.GIBBERISH:
return (
'Gibberish (imaginary words vaguely reminiscent of'
' English; translated phrases should be roughly'
' 150%-200% as long as the English versions)'
)
if self is cls.GREEK:
return 'Greek'
if self is cls.HINDI:
return 'Hindi'
if self is cls.HUNGARIAN:
return 'Hungarian'
if self is cls.INDONESIAN:
return 'Indonesian'
if self is cls.ITALIAN:
return 'Italian'
if self is cls.KOREAN:
return 'Korean'
if self is cls.MALAY:
return 'Malay'
if self is cls.PERSIAN:
return 'Persian'
if self is cls.POLISH:
return 'Polish'
if self is cls.ROMANIAN:
return 'Romanian'
if self is cls.RUSSIAN:
return 'Russian'
if self is cls.SERBIAN:
return 'Serbian'
if self is cls.SPANISH:
return 'Spanish'
if self is cls.SPANISH_LATIN_AMERICA:
return 'Spanish (Latin America)'
if self is cls.SPANISH_SPAIN:
return 'Spanish (Spain)'
if self is cls.SLOVAK:
return 'Slovak'
if self is cls.SWEDISH:
return 'Swedish'
if self is cls.TAMIL:
return 'Tamil'
if self is cls.THAI:
return 'Thai'
if self is cls.TURKISH:
return 'Turkish'
if self is cls.UKRAINIAN:
return 'Ukrainian'
if self is cls.VENETIAN:
return 'Venetian'
if self is cls.VIETNAMESE:
return 'Vietnamese'
if self is cls.KAZAKH:
return 'Kazakh'
if self is cls.JAPANESE:
return 'Japanese'
# Make sure we've covered all cases.
assert_never(self)
[docs]
@cached_property
def resolved(self) -> LocaleResolved:
"""Return the associated resolved locale."""
# pylint: disable=too-many-return-statements
# pylint: disable=too-many-branches
cls = Locale
R = LocaleResolved
if self is cls.ENGLISH:
return R.ENGLISH
if self is cls.CHINESE_SIMPLIFIED or self is cls.CHINESE:
return R.CHINESE_SIMPLIFIED
if self is cls.CHINESE_TRADITIONAL:
return R.CHINESE_TRADITIONAL
if self is cls.PORTUGUESE_BRAZIL or self is cls.PORTUGUESE:
return R.PORTUGUESE_BRAZIL
if self is cls.PORTUGUESE_PORTUGAL:
return R.PORTUGUESE_PORTUGAL
if self is cls.SPANISH_LATIN_AMERICA or self is cls.SPANISH:
return R.SPANISH_LATIN_AMERICA
if self is cls.SPANISH_SPAIN:
return R.SPANISH_SPAIN
if self is cls.ARABIC:
return R.ARABIC
if self is cls.BELARUSSIAN:
return R.BELARUSSIAN
if self is cls.CROATIAN:
return R.CROATIAN
if self is cls.CZECH:
return R.CZECH
if self is cls.DANISH:
return R.DANISH
if self is cls.DUTCH:
return R.DUTCH
if self is cls.PIRATE_SPEAK:
return R.PIRATE_SPEAK
if self is cls.ESPERANTO:
return R.ESPERANTO
if self is cls.FILIPINO:
return R.FILIPINO
if self is cls.FRENCH:
return R.FRENCH
if self is cls.GERMAN:
return R.GERMAN
if self is cls.GIBBERISH:
return R.GIBBERISH
if self is cls.GREEK:
return R.GREEK
if self is cls.HINDI:
return R.HINDI
if self is cls.HUNGARIAN:
return R.HUNGARIAN
if self is cls.INDONESIAN:
return R.INDONESIAN
if self is cls.ITALIAN:
return R.ITALIAN
if self is cls.KOREAN:
return R.KOREAN
if self is cls.MALAY:
return R.MALAY
if self is cls.PERSIAN:
return R.PERSIAN
if self is cls.POLISH:
return R.POLISH
if self is cls.ROMANIAN:
return R.ROMANIAN
if self is cls.RUSSIAN:
return R.RUSSIAN
if self is cls.SERBIAN:
return R.SERBIAN
if self is cls.SLOVAK:
return R.SLOVAK
if self is cls.SWEDISH:
return R.SWEDISH
if self is cls.TAMIL:
return R.TAMIL
if self is cls.THAI:
return R.THAI
if self is cls.TURKISH:
return R.TURKISH
if self is cls.UKRAINIAN:
return R.UKRAINIAN
if self is cls.VENETIAN:
return R.VENETIAN
if self is cls.VIETNAMESE:
return R.VIETNAMESE
if self is cls.KAZAKH:
return R.KAZAKH
if self is cls.JAPANESE:
return R.JAPANESE
# Make sure we're covering all cases.
assert_never(self)
[docs]
class LocaleResolved(Enum):
"""A resolved :class:`Locale` for use in logic.
These values should never be stored or transmitted and should always
come from resolving a :class:`Locale` which *can* be
stored/transmitted. This gives us the freedom to revise this list as
needed to keep our actual list of implemented resolved-locales as
trim as possible.
"""
ENGLISH = 'eng'
CHINESE_TRADITIONAL = 'chn_tr'
CHINESE_SIMPLIFIED = 'chn_sim'
PORTUGUESE_PORTUGAL = 'prtg_pr'
PORTUGUESE_BRAZIL = 'prtg_brz'
ARABIC = 'arabc'
BELARUSSIAN = 'blrs'
CROATIAN = 'croat'
CZECH = 'czch'
DANISH = 'dnsh'
DUTCH = 'dtch'
PIRATE_SPEAK = 'pirate'
ESPERANTO = 'esprnto'
FILIPINO = 'filp'
FRENCH = 'frnch'
GERMAN = 'grmn'
GIBBERISH = 'gibber'
GREEK = 'greek'
HINDI = 'hndi'
HUNGARIAN = 'hngr'
INDONESIAN = 'indnsn'
ITALIAN = 'italn'
KOREAN = 'kor'
MALAY = 'mlay'
PERSIAN = 'pers'
POLISH = 'pol'
ROMANIAN = 'rom'
RUSSIAN = 'rusn'
SERBIAN = 'srbn'
SPANISH_LATIN_AMERICA = 'spn_lat'
SPANISH_SPAIN = 'spn_spn'
SLOVAK = 'slvk'
SWEDISH = 'swed'
TAMIL = 'taml'
THAI = 'thai'
TURKISH = 'turk'
UKRAINIAN = 'ukrn'
VENETIAN = 'venetn'
VIETNAMESE = 'viet'
KAZAKH = 'kazk'
JAPANESE = 'jpn'
# Note: We use if-statement chains here so we can use assert_never()
# to ensure we cover all existing values. But we cache lookups so
# that we only have to go through those long if-statement chains
# once per enum value.
[docs]
@cached_property
def locale(self) -> Locale:
"""Return a locale that resolves to this resolved locale.
In some cases, such as when presenting locale options to the
user, it makes sense to iterate over resolved locale values, as
regular locales may include obsolete or redundant values. When
storing locale values to disk or transmitting them, however, it
is important to use plain locales. This method can be used to
get back to a plain locale from a resolved one.
"""
# pylint: disable=too-many-return-statements
# pylint: disable=too-many-branches
cls = LocaleResolved
if self is cls.ENGLISH:
return Locale.ENGLISH
if self is cls.CHINESE_TRADITIONAL:
return Locale.CHINESE_TRADITIONAL
if self is cls.CHINESE_SIMPLIFIED:
return Locale.CHINESE_SIMPLIFIED
if self is cls.PORTUGUESE_PORTUGAL:
return Locale.PORTUGUESE_PORTUGAL
if self is cls.PORTUGUESE_BRAZIL:
return Locale.PORTUGUESE_BRAZIL
if self is cls.ARABIC:
return Locale.ARABIC
if self is cls.BELARUSSIAN:
return Locale.BELARUSSIAN
if self is cls.CROATIAN:
return Locale.CROATIAN
if self is cls.CZECH:
return Locale.CZECH
if self is cls.DANISH:
return Locale.DANISH
if self is cls.DUTCH:
return Locale.DUTCH
if self is cls.PIRATE_SPEAK:
return Locale.PIRATE_SPEAK
if self is cls.ESPERANTO:
return Locale.ESPERANTO
if self is cls.FILIPINO:
return Locale.FILIPINO
if self is cls.FRENCH:
return Locale.FRENCH
if self is cls.GERMAN:
return Locale.GERMAN
if self is cls.GIBBERISH:
return Locale.GIBBERISH
if self is cls.GREEK:
return Locale.GREEK
if self is cls.HINDI:
return Locale.HINDI
if self is cls.HUNGARIAN:
return Locale.HUNGARIAN
if self is cls.INDONESIAN:
return Locale.INDONESIAN
if self is cls.ITALIAN:
return Locale.ITALIAN
if self is cls.KOREAN:
return Locale.KOREAN
if self is cls.MALAY:
return Locale.MALAY
if self is cls.PERSIAN:
return Locale.PERSIAN
if self is cls.POLISH:
return Locale.POLISH
if self is cls.ROMANIAN:
return Locale.ROMANIAN
if self is cls.RUSSIAN:
return Locale.RUSSIAN
if self is cls.SERBIAN:
return Locale.SERBIAN
if self is cls.SPANISH_LATIN_AMERICA:
return Locale.SPANISH_LATIN_AMERICA
if self is cls.SPANISH_SPAIN:
return Locale.SPANISH_SPAIN
if self is cls.SLOVAK:
return Locale.SLOVAK
if self is cls.SWEDISH:
return Locale.SWEDISH
if self is cls.TAMIL:
return Locale.TAMIL
if self is cls.THAI:
return Locale.THAI
if self is cls.TURKISH:
return Locale.TURKISH
if self is cls.UKRAINIAN:
return Locale.UKRAINIAN
if self is cls.VENETIAN:
return Locale.VENETIAN
if self is cls.VIETNAMESE:
return Locale.VIETNAMESE
if self is cls.KAZAKH:
return Locale.KAZAKH
if self is cls.JAPANESE:
return Locale.JAPANESE
# Make sure we're covering all cases.
assert_never(self)
[docs]
@cached_property
def endonym(self) -> str:
"""This locale's name written in this locale's own language.
Static per-locale data, deliberately *not* a translated string:
a language picker shows every option at once, which no
single-locale string table can do (a client holds one locale's
strings at a time). It is also what lets a user find their
language whatever the ui is currently set to. Pair it with a
translated language name -- see the ``strings/locales`` group in
BaCommonAssets -- to render e.g. "Svenska (Swedish)".
Values match what shipped in the legacy ``lang_names_translated``
blob, so players see no churn, with these deliberate deviations:
* English was simply absent there and is supplied here.
* Slovak's stray trailing space is dropped.
* Latin-American Spanish gains the accent it was missing
("Latinoamérica").
* Gibberish's was 'Abuktarika', which sorted it to the very top
of every picker -- a surprising spot for a joke locale. It now
starts with a G so it lands where someone hunting for it would
look, keeping the mock-English style of the locale's own
output ('Germaunish', 'Sveendishsprok').
* Persian's wrapping bidi controls (U+2066/U+200E) are dropped.
Directional isolation is a *rendering* concern, and both
consumers already give each entry its own container (an html
``<option>``, a popup-menu row), so the run cannot bleed into
a neighbor. A caller placing one of these inline in mixed
text should isolate it there.
"""
# pylint: disable=too-many-branches
# pylint: disable=too-many-return-statements
cls = LocaleResolved
if self is cls.ENGLISH:
return 'English'
if self is cls.CHINESE_TRADITIONAL:
return '繁體中文'
if self is cls.CHINESE_SIMPLIFIED:
return '简体中文'
if self is cls.PORTUGUESE_PORTUGAL:
return 'Português (Portugal)'
if self is cls.PORTUGUESE_BRAZIL:
return 'Português (Brasil)'
if self is cls.ARABIC:
return 'العربية'
if self is cls.BELARUSSIAN:
return 'Беларуская'
if self is cls.CROATIAN:
return 'Hrvatski'
if self is cls.CZECH:
return 'Čeština'
if self is cls.DANISH:
return 'Dansk'
if self is cls.DUTCH:
return 'Nederlands'
if self is cls.PIRATE_SPEAK:
return 'Pirate Speak'
if self is cls.ESPERANTO:
return 'Esperanto'
if self is cls.FILIPINO:
return 'Wikang Pilipino'
if self is cls.FRENCH:
return 'Français'
if self is cls.GERMAN:
return 'Deutsch'
if self is cls.GIBBERISH:
return 'Gibbereesh'
if self is cls.GREEK:
return 'Ελληνικά'
if self is cls.HINDI:
return 'हिंदी'
if self is cls.HUNGARIAN:
return 'Magyar'
if self is cls.INDONESIAN:
return 'Bahasa Indonesia'
if self is cls.ITALIAN:
return 'Italiano'
if self is cls.KOREAN:
return '한국어'
if self is cls.MALAY:
return 'Melayu'
if self is cls.PERSIAN:
return 'فارسی'
if self is cls.POLISH:
return 'Polski'
if self is cls.ROMANIAN:
return 'Română'
if self is cls.RUSSIAN:
return 'Русский'
if self is cls.SERBIAN:
return 'Српски'
if self is cls.SPANISH_LATIN_AMERICA:
return 'Español (Latinoamérica)'
if self is cls.SPANISH_SPAIN:
return 'Español (España)'
if self is cls.SLOVAK:
return 'Slovenčina'
if self is cls.SWEDISH:
return 'Svenska'
if self is cls.TAMIL:
return 'தமிழ்'
if self is cls.THAI:
return 'ภาษาไทย'
if self is cls.TURKISH:
return 'Türkçe'
if self is cls.UKRAINIAN:
return 'Українська'
if self is cls.VENETIAN:
return 'Veneto'
if self is cls.VIETNAMESE:
return 'Tiếng Việt'
if self is cls.KAZAKH:
return 'Қазақша'
if self is cls.JAPANESE:
return '日本語'
# Make sure we're covering all cases.
assert_never(self)
[docs]
@cached_property
def endonym_sort_key(self) -> str:
"""Sort key for listing locales by :attr:`endonym`.
Endonym order is what a language picker wants: it is the half of
the label the eye scans for, and unlike ordering by translated
name it does not reshuffle the whole list when the ui language
changes.
Accents are folded so a leading diacritic doesn't exile an entry
from its own alphabet -- raw codepoint order files "Čeština"
after "Wikang Pilipino". Non-Latin scripts still land after Latin
ones, which reads as a reasonable grouping rather than an error.
Deliberately not full locale-aware collation: that needs ICU, and
the result here is stable and good enough for a few dozen
entries.
Lives here rather than in each picker because there are two of
them -- the client's settings window and the master server's
account-settings page -- and they silently disagreed about
ordering until 2026-07-30.
"""
decomposed = unicodedata.normalize('NFD', self.endonym)
return ''.join(
c for c in decomposed if not unicodedata.combining(c)
).casefold()
[docs]
@cached_property
def duration_separator(self) -> str:
# pylint: disable=too-many-branches
# pylint: disable=too-many-return-statements
"""The joiner between composed duration parts ("1h 23m").
Locale *data*, not translated content, same as
:attr:`decimal_mark`: most languages join abbreviated duration
parts with a space, while CJK compounds join with none
("1\u6642\u959345\u5206"). Curated here and applied by
formatting code so it can never be a confidently wrong
translation, and so a new locale is a *type* error rather than
a silent space.
"""
cls = LocaleResolved
if self is cls.ENGLISH:
return ' '
if self is cls.CHINESE_TRADITIONAL:
return ''
if self is cls.CHINESE_SIMPLIFIED:
return ''
if self is cls.PORTUGUESE_PORTUGAL:
return ' '
if self is cls.PORTUGUESE_BRAZIL:
return ' '
if self is cls.ARABIC:
return ' '
if self is cls.BELARUSSIAN:
return ' '
if self is cls.CROATIAN:
return ' '
if self is cls.CZECH:
return ' '
if self is cls.DANISH:
return ' '
if self is cls.DUTCH:
return ' '
if self is cls.PIRATE_SPEAK:
return ' '
if self is cls.ESPERANTO:
return ' '
if self is cls.FILIPINO:
return ' '
if self is cls.FRENCH:
return ' '
if self is cls.GERMAN:
return ' '
if self is cls.GIBBERISH:
return ' '
if self is cls.GREEK:
return ' '
if self is cls.HINDI:
return ' '
if self is cls.HUNGARIAN:
return ' '
if self is cls.INDONESIAN:
return ' '
if self is cls.ITALIAN:
return ' '
if self is cls.KOREAN:
return ' '
if self is cls.MALAY:
return ' '
if self is cls.PERSIAN:
return ' '
if self is cls.POLISH:
return ' '
if self is cls.ROMANIAN:
return ' '
if self is cls.RUSSIAN:
return ' '
if self is cls.SERBIAN:
return ' '
if self is cls.SPANISH_LATIN_AMERICA:
return ' '
if self is cls.SPANISH_SPAIN:
return ' '
if self is cls.SLOVAK:
return ' '
if self is cls.SWEDISH:
return ' '
if self is cls.TAMIL:
return ' '
if self is cls.THAI:
return ' '
if self is cls.TURKISH:
return ' '
if self is cls.UKRAINIAN:
return ' '
if self is cls.VENETIAN:
return ' '
if self is cls.VIETNAMESE:
return ' '
if self is cls.KAZAKH:
return ' '
if self is cls.JAPANESE:
return ''
# Make sure we cover all cases.
assert_never(self)
[docs]
@cached_property
def decimal_mark(self) -> str:
# pylint: disable=too-many-branches
# pylint: disable=too-many-return-statements
"""The character separating a number's whole and fraction parts.
Locale *data*, not translated content: a decimal mark is a
fact about a language, and asking a translation model for
one invites a confidently wrong answer that no reviewer
would catch by reading the string. So it is curated here
and applied by formatting code rather than authored into
any asset package.
Deliberately covers only the mark. Digit grouping is not
modelled: our formatted numbers scale their units (``1.2
GB``, never ``1234.5 MB``), so a group separator has
nothing to separate, and skipping it avoids the messier
per-locale rules (``1,234,567`` / ``1 234 567`` /
``12,34,567``). Digit *shaping* is likewise out: locales
that could use non-ASCII digits read Western ones fine.
Arabic and Persian are ``'.'`` rather than ``'\u066b'``
on purpose -- that mark pairs with Eastern Arabic digits,
which we do not emit.
"""
cls = LocaleResolved
if self is cls.ENGLISH:
return '.'
if self is cls.CHINESE_TRADITIONAL:
return '.'
if self is cls.CHINESE_SIMPLIFIED:
return '.'
if self is cls.PORTUGUESE_PORTUGAL:
return ','
if self is cls.PORTUGUESE_BRAZIL:
return ','
if self is cls.ARABIC:
return '.'
if self is cls.BELARUSSIAN:
return ','
if self is cls.CROATIAN:
return ','
if self is cls.CZECH:
return ','
if self is cls.DANISH:
return ','
if self is cls.DUTCH:
return ','
if self is cls.PIRATE_SPEAK:
return '.'
if self is cls.ESPERANTO:
return ','
if self is cls.FILIPINO:
return '.'
if self is cls.FRENCH:
return ','
if self is cls.GERMAN:
return ','
if self is cls.GIBBERISH:
return '.'
if self is cls.GREEK:
return ','
if self is cls.HINDI:
return '.'
if self is cls.HUNGARIAN:
return ','
if self is cls.INDONESIAN:
return ','
if self is cls.ITALIAN:
return ','
if self is cls.KOREAN:
return '.'
if self is cls.MALAY:
return '.'
if self is cls.PERSIAN:
return '.'
if self is cls.POLISH:
return ','
if self is cls.ROMANIAN:
return ','
if self is cls.RUSSIAN:
return ','
if self is cls.SERBIAN:
return ','
if self is cls.SPANISH_LATIN_AMERICA:
return ','
if self is cls.SPANISH_SPAIN:
return ','
if self is cls.SLOVAK:
return ','
if self is cls.SWEDISH:
return ','
if self is cls.TAMIL:
return '.'
if self is cls.THAI:
return '.'
if self is cls.TURKISH:
return ','
if self is cls.UKRAINIAN:
return ','
if self is cls.VENETIAN:
return ','
if self is cls.VIETNAMESE:
return ','
if self is cls.KAZAKH:
return ','
if self is cls.JAPANESE:
return '.'
assert_never(self)
[docs]
@cached_property
def tag(self) -> str:
# pylint: disable=too-many-statements
"""An IETF BCP 47 tag for this locale.
This is often simply a language code ('en') but may in some
cases include the country ('pt-BR') or script ('zh-Hans').
Locales which are not "real" will include an 'x' in the middle
('en-x-pirate').
"""
# pylint: disable=too-many-branches
cls = LocaleResolved
val: str | None = None
if self is cls.ENGLISH:
val = 'en'
elif self is cls.CHINESE_TRADITIONAL:
val = 'zh-Hant'
elif self is cls.CHINESE_SIMPLIFIED:
val = 'zh-Hans'
elif self is cls.PORTUGUESE_PORTUGAL:
val = 'pt-PT'
elif self is cls.PORTUGUESE_BRAZIL:
val = 'pt-BR'
elif self is cls.ARABIC:
val = 'ar'
elif self is cls.BELARUSSIAN:
val = 'be'
elif self is cls.CROATIAN:
val = 'hr'
elif self is cls.CZECH:
val = 'cs'
elif self is cls.DANISH:
val = 'da'
elif self is cls.DUTCH:
val = 'nl'
elif self is cls.PIRATE_SPEAK:
# 'x' in BCP 47 denotes private-use values.
val = 'en-x-pirate'
elif self is cls.ESPERANTO:
val = 'eo'
elif self is cls.FILIPINO:
val = 'fil'
elif self is cls.FRENCH:
val = 'fr'
elif self is cls.GERMAN:
val = 'de'
elif self is cls.GIBBERISH:
# 'x' in BCP 47 denotes private-use values.
val = 'en-x-gibberish'
elif self is cls.GREEK:
val = 'el'
elif self is cls.HINDI:
val = 'hi'
elif self is cls.HUNGARIAN:
val = 'hu'
elif self is cls.INDONESIAN:
val = 'id'
elif self is cls.ITALIAN:
val = 'it'
elif self is cls.KOREAN:
val = 'ko'
elif self is cls.MALAY:
val = 'ms'
elif self is cls.PERSIAN:
val = 'fa'
elif self is cls.POLISH:
val = 'pl'
elif self is cls.ROMANIAN:
val = 'ro'
elif self is cls.RUSSIAN:
val = 'ru'
elif self is cls.SERBIAN:
val = 'sr'
elif self is cls.SPANISH_LATIN_AMERICA:
val = 'es-419'
elif self is cls.SPANISH_SPAIN:
val = 'es-ES'
elif self is cls.SLOVAK:
val = 'sk'
elif self is cls.SWEDISH:
val = 'sv'
elif self is cls.TAMIL:
val = 'ta'
elif self is cls.THAI:
val = 'th'
elif self is cls.TURKISH:
val = 'tr'
elif self is cls.UKRAINIAN:
val = 'uk'
elif self is cls.VENETIAN:
val = 'vec'
elif self is cls.VIETNAMESE:
val = 'vi'
elif self is cls.KAZAKH:
val = 'kk'
elif self is cls.JAPANESE:
val = 'ja'
else:
# Make sure we cover all cases.
assert_never(self)
assert_type(val, str)
# Sanity check: the tag we return should lead back to us if we
# use it to get a Locale and then resolve that Locale. Make some
# noise if not so we can fix it.
lrcheck = LocaleResolved.from_tag(val)
if lrcheck is not self:
logging.warning(
'LocaleResolved.from_tag().resolved for "%s" yielded %s;'
' expected %s.',
val,
lrcheck.name,
self.name,
)
return val
[docs]
@staticmethod
def from_tag(tag: str) -> LocaleResolved:
"""Return a locale for a given string tag.
Tags can be provided in BCP 47 form ('en-US') or POSIX locale
string form ('en_US.UTF-8'). A tag naming a language we have no
locale for falls back to English (with a warning, so we can add
it); a malformed tag raises :class:`ValueError`.
Use :meth:`from_tag_or_none` when a non-match is an ordinary
outcome rather than something to complain about -- negotiating a
browser's ``Accept-Language`` list, say, where most entries are
expected to miss.
"""
out = LocaleResolved._from_tag_impl(tag)
if out is None:
# Make noise if we come across something unexpected so we
# can add it.
fallback = LocaleResolved.ENGLISH
logging.warning(
'%s: Unknown tag "%s"; returning %s.',
LocaleResolved.__name__,
tag,
fallback.name,
)
return fallback
return out
[docs]
@staticmethod
def from_tag_or_none(tag: str) -> LocaleResolved | None:
"""Return a locale for a string tag, or None if we have none.
The quiet counterpart to :meth:`from_tag`: returns ``None``
instead of warning and falling back to English, and swallows the
malformed-tag :class:`ValueError`. This is what locale
negotiation wants -- walking a client's preference list, a miss
is the normal case and must be distinguishable from a genuine
match on English.
Note that an unknown *region* within a known language is still a
match (``zh-XX`` resolves to simplified Chinese), and still
warns -- that one is worth adding.
"""
try:
return LocaleResolved._from_tag_impl(tag)
except ValueError:
return None
@staticmethod
@lru_cache(maxsize=128)
def _from_tag_impl(tag: str) -> LocaleResolved | None:
"""Resolve a tag, or None if its language is unknown to us.
Raises :class:`ValueError` for a structurally invalid tag. The
shared implementation behind :meth:`from_tag` and
:meth:`from_tag_or_none`, which differ only in how they report a
non-match.
"""
# pylint: disable=too-many-branches
# pylint: disable=too-many-return-statements
cls = LocaleResolved
# POSIX locale strings can contain a dot followed by an
# encoding. Strip that off.
tag2 = tag.split('.')[0]
# Normalize things to lowercase and underscores (we should see
# 'zh_HANT' and 'zh-Hant' as the same).
bits = [bit.lower() for bit in tag2.replace('-', '_').split('_')]
if not bits or not bits[0]:
raise ValueError(f'Invalid tag "{tag}".')
lang = bits[0]
extras = bits[1:]
if lang == 'en':
if 'x' in extras and 'pirate' in extras:
return cls.PIRATE_SPEAK
if 'x' in extras and 'gibberish' in extras:
return cls.GIBBERISH
return cls.ENGLISH
if lang == 'zh':
# With no extras, default to simplified.
if not extras or any(val in extras for val in ['hans', 'cn', 'sg']):
return cls.CHINESE_SIMPLIFIED
if any(val in extras for val in ['hant', 'tw']):
return cls.CHINESE_TRADITIONAL
# Make noise if we come across something unexpected so we
# can add it.
fallback = cls.CHINESE_SIMPLIFIED
logging.warning(
'%s: Unknown Chinese tag variant "%s"; returning %s.',
cls.__name__,
tag,
fallback.name,
)
return fallback
if lang == 'pt':
# With no extras, default to Brazil.
if not extras or 'br' in extras:
return cls.PORTUGUESE_BRAZIL
if any(
val in extras
for val in ['pt', 'ao', 'mz', 'tl', 'cv', 'gw', 'st']
):
return cls.PORTUGUESE_PORTUGAL
# Make noise if we come across something unexpected so we
# can add it.
fallback = cls.PORTUGUESE_BRAZIL
logging.warning(
'%s: Unknown Portuguese tag variant "%s"; returning %s.',
cls.__name__,
tag,
fallback.name,
)
return fallback
if lang == 'es':
# With no extras, default to latin-america spanish.
if not extras or any(
val in extras
for val in [
'419', # Latin America / Carribean region
'mx', # Mexico
'ar', # Argentina
'co', # Colombia
'cl', # Chile
'pe', # Peru
've', # Venezuela
'cr', # Costa Rica
'pr', # Puerto Rico
'do', # Dominican Republic
'uy', # Uruguay
'ec', # Ecuador
'pa', # Panama
'bo', # Bolivia
'py', # Paraguay
'gt', # Guatemala
'hn', # Honduras
'sv', # El Salvador
'ni', # Nicaragua
'cu', # Cuba
'us', # United States (es-US is latin-american)
]
):
return cls.SPANISH_LATIN_AMERICA
if 'es' in extras:
return cls.SPANISH_SPAIN
# Make noise if we come across something unexpected so we
# can add it.
fallback = cls.SPANISH_LATIN_AMERICA
logging.warning(
'%s: Unknown Spanish tag variant "%s"; returning %s.',
cls.__name__,
tag,
fallback.name,
)
return fallback
if lang == 'c':
# The C.UTF-8 is a minimal locale defined by POSIX we
# sometimes run into.
return cls.ENGLISH
if lang == 'ar':
return cls.ARABIC
if lang == 'be':
return cls.BELARUSSIAN
if lang == 'hr':
return cls.CROATIAN
if lang == 'cs':
return cls.CZECH
if lang == 'da':
return cls.DANISH
if lang == 'nl':
return cls.DUTCH
if lang == 'eo':
return cls.ESPERANTO
if lang == 'fil':
return cls.FILIPINO
if lang == 'fr':
return cls.FRENCH
if lang == 'de':
return cls.GERMAN
if lang == 'el':
return cls.GREEK
if lang == 'hi':
return cls.HINDI
if lang == 'hu':
return cls.HUNGARIAN
if lang == 'id':
return cls.INDONESIAN
if lang == 'it':
return cls.ITALIAN
if lang == 'ko':
return cls.KOREAN
if lang == 'ms':
return cls.MALAY
if lang == 'fa':
return cls.PERSIAN
if lang == 'pl':
return cls.POLISH
if lang == 'ro':
return cls.ROMANIAN
if lang == 'ru':
return cls.RUSSIAN
if lang == 'sr':
return cls.SERBIAN
if lang == 'sk':
return cls.SLOVAK
if lang == 'sv':
return cls.SWEDISH
if lang == 'ta':
return cls.TAMIL
if lang == 'th':
return cls.THAI
if lang == 'tr':
return cls.TURKISH
if lang == 'uk':
return cls.UKRAINIAN
if lang == 'vec':
return cls.VENETIAN
if lang == 'vi':
return cls.VIETNAMESE
if lang == 'kk':
return cls.KAZAKH
if lang == 'ja':
return cls.JAPANESE
# An unknown language. Callers decide whether that's worth
# complaining about (see from_tag / from_tag_or_none).
return None
# Docs-generation hack; import some stuff that we likely only forward-declared
# in our actual source code so that docs tools can find it.
from typing import (Coroutine, Any, Literal, Callable,
Generator, Awaitable, Sequence, Self)
import asyncio
from concurrent.futures import Future
from pathlib import Path
from enum import Enum