Skip to content

Library API

GettextWrapper

A wrapper for the gettext module

Source code in streamlit_gettext/streamlit_gettext.py
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
class GettextWrapper:
    """
    A wrapper for the gettext module
    """

    locale_path: Path
    domain: str

    def __init__(self, locale_path: str | Path, domain: str = "messages") -> None:
        self.locale_path = Path(locale_path)
        self.domain = domain

    def _get_session_state_key(self) -> str:
        return f"streamlit_gettext.preferred_languages:{(str(self.locale_path.resolve()), self.domain)!r}"

    def set_preferred_languages(self, languages: Iterable[str] | None) -> None:
        """
        Set preferred languages for this session. None or an empty iterable restores browser detection.
        """
        preferred_languages = list(languages) if languages is not None else []
        session_state_key = self._get_session_state_key()
        if preferred_languages:
            st.session_state[session_state_key] = preferred_languages
        else:
            st.session_state.pop(session_state_key, None)

    def get_preferred_languages(self) -> list[str]:
        """
        Get preferred languages from the browser if preferred languages are not set explicitly
        """
        preferred_languages = st.session_state.get(self._get_session_state_key())
        if preferred_languages:
            return list(preferred_languages)

        return self.get_preferred_languages_from_browser()

    @staticmethod
    def _normalize_language(language: str) -> str:
        """Normalize a language tag to gettext locale form."""
        return language.replace("-", "_").casefold()

    def get_preferred_languages_from_browser(self) -> list[str]:
        """
        Get concrete browser languages by descending quality, preserving order for ties.
        """
        accept_language = st.context.headers.get("Accept-Language") or ""
        weighted_languages: list[tuple[str, float]] = []
        for entry in accept_language.split(","):
            parsed = self._parse_accept_language_entry(entry)
            if parsed is not None:
                weighted_languages.append(parsed)

        weighted_languages.sort(key=lambda item: item[1], reverse=True)
        languages: list[str] = []
        seen: set[str] = set()
        for language, _weight in weighted_languages:
            normalized = self._normalize_language(language)
            if normalized not in seen:
                seen.add(normalized)
                languages.append(language.replace("-", "_"))
        return languages

    @staticmethod
    def _parse_accept_language_entry(entry: str) -> tuple[str, float] | None:
        """Return a concrete language and weight, or None for unusable entries."""
        match = re.fullmatch(
            r"[ \t]*([a-zA-Z]{1,8}(?:-[a-zA-Z0-9]{1,8})*|\*)[ \t]*"
            r"(?:;[ \t]*[qQ]=(0(?:\.[0-9]{0,3})?|1(?:\.0{0,3})?)[ \t]*)?",
            entry,
        )
        if match is None:
            return None
        language, quality = match.groups()
        weight = float(quality) if quality is not None else 1.0
        # A wildcard does not identify a concrete gettext catalog.
        if language == "*" or weight == 0:
            return None
        return language, weight

    def translation(self, languages: Iterable[str] | None = None) -> _gettext_module.NullTranslations:
        if languages is not None:
            languages = [language.replace("-", "_") for language in languages]
        return _gettext_module.translation(
            domain=self.domain,
            localedir=self.locale_path,
            languages=languages,
            fallback=True,
        )

    def gettext(self, message: str) -> str:
        """
        Get the translation of a message
        """
        translation = self.translation(self.get_preferred_languages())
        return translation.gettext(message)

    def ngettext(self, singular: str, plural: str, n: int) -> str:
        """
        Get the plural form of a message
        """
        translation = self.translation(self.get_preferred_languages())
        return translation.ngettext(singular, plural, n)

    def pgettext(self, context: str, message: str) -> str:
        """
        Get the translation of a message with a context
        """
        translation = self.translation(self.get_preferred_languages())
        return translation.pgettext(context, message)

    def npgettext(self, context: str, singular: str, plural: str, n: int) -> str:
        """
        Get the plural form of a message with a context
        """
        translation = self.translation(self.get_preferred_languages())
        return translation.npgettext(context, singular, plural, n)

    def get_available_languages(self) -> list[str]:
        """
        Get languages available in the locale directory
        """
        try:
            locale_directories = list(self.locale_path.iterdir())
        except FileNotFoundError:
            locale_directories = []

        language_codes = {
            path.name
            for path in locale_directories
            if path.is_dir() and (path / "LC_MESSAGES" / f"{self.domain}.mo").is_file()
        }
        language_codes.add("en")

        preferred_languages = [
            self._normalize_language(language) for language in self.get_preferred_languages_from_browser()
        ]

        def sort_key(language: str) -> tuple[int, int, str]:
            """Prefer exact locale matches, then compatible language fallbacks."""
            normalized = self._normalize_language(language)
            for index, preferred in enumerate(preferred_languages):
                if normalized == preferred:
                    return index, 0, language.casefold()
                if normalized == preferred.split("_")[0] or preferred == normalized.split("_")[0]:
                    return index, 1, language.casefold()
            return len(preferred_languages), 0, language.casefold()

        return sorted(language_codes, key=sort_key)

get_available_languages()

Get languages available in the locale directory

Source code in streamlit_gettext/streamlit_gettext.py
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def get_available_languages(self) -> list[str]:
    """
    Get languages available in the locale directory
    """
    try:
        locale_directories = list(self.locale_path.iterdir())
    except FileNotFoundError:
        locale_directories = []

    language_codes = {
        path.name
        for path in locale_directories
        if path.is_dir() and (path / "LC_MESSAGES" / f"{self.domain}.mo").is_file()
    }
    language_codes.add("en")

    preferred_languages = [
        self._normalize_language(language) for language in self.get_preferred_languages_from_browser()
    ]

    def sort_key(language: str) -> tuple[int, int, str]:
        """Prefer exact locale matches, then compatible language fallbacks."""
        normalized = self._normalize_language(language)
        for index, preferred in enumerate(preferred_languages):
            if normalized == preferred:
                return index, 0, language.casefold()
            if normalized == preferred.split("_")[0] or preferred == normalized.split("_")[0]:
                return index, 1, language.casefold()
        return len(preferred_languages), 0, language.casefold()

    return sorted(language_codes, key=sort_key)

get_preferred_languages()

Get preferred languages from the browser if preferred languages are not set explicitly

Source code in streamlit_gettext/streamlit_gettext.py
40
41
42
43
44
45
46
47
48
def get_preferred_languages(self) -> list[str]:
    """
    Get preferred languages from the browser if preferred languages are not set explicitly
    """
    preferred_languages = st.session_state.get(self._get_session_state_key())
    if preferred_languages:
        return list(preferred_languages)

    return self.get_preferred_languages_from_browser()

get_preferred_languages_from_browser()

Get concrete browser languages by descending quality, preserving order for ties.

Source code in streamlit_gettext/streamlit_gettext.py
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def get_preferred_languages_from_browser(self) -> list[str]:
    """
    Get concrete browser languages by descending quality, preserving order for ties.
    """
    accept_language = st.context.headers.get("Accept-Language") or ""
    weighted_languages: list[tuple[str, float]] = []
    for entry in accept_language.split(","):
        parsed = self._parse_accept_language_entry(entry)
        if parsed is not None:
            weighted_languages.append(parsed)

    weighted_languages.sort(key=lambda item: item[1], reverse=True)
    languages: list[str] = []
    seen: set[str] = set()
    for language, _weight in weighted_languages:
        normalized = self._normalize_language(language)
        if normalized not in seen:
            seen.add(normalized)
            languages.append(language.replace("-", "_"))
    return languages

gettext(message)

Get the translation of a message

Source code in streamlit_gettext/streamlit_gettext.py
103
104
105
106
107
108
def gettext(self, message: str) -> str:
    """
    Get the translation of a message
    """
    translation = self.translation(self.get_preferred_languages())
    return translation.gettext(message)

ngettext(singular, plural, n)

Get the plural form of a message

Source code in streamlit_gettext/streamlit_gettext.py
110
111
112
113
114
115
def ngettext(self, singular: str, plural: str, n: int) -> str:
    """
    Get the plural form of a message
    """
    translation = self.translation(self.get_preferred_languages())
    return translation.ngettext(singular, plural, n)

npgettext(context, singular, plural, n)

Get the plural form of a message with a context

Source code in streamlit_gettext/streamlit_gettext.py
124
125
126
127
128
129
def npgettext(self, context: str, singular: str, plural: str, n: int) -> str:
    """
    Get the plural form of a message with a context
    """
    translation = self.translation(self.get_preferred_languages())
    return translation.npgettext(context, singular, plural, n)

pgettext(context, message)

Get the translation of a message with a context

Source code in streamlit_gettext/streamlit_gettext.py
117
118
119
120
121
122
def pgettext(self, context: str, message: str) -> str:
    """
    Get the translation of a message with a context
    """
    translation = self.translation(self.get_preferred_languages())
    return translation.pgettext(context, message)

set_preferred_languages(languages)

Set preferred languages for this session. None or an empty iterable restores browser detection.

Source code in streamlit_gettext/streamlit_gettext.py
29
30
31
32
33
34
35
36
37
38
def set_preferred_languages(self, languages: Iterable[str] | None) -> None:
    """
    Set preferred languages for this session. None or an empty iterable restores browser detection.
    """
    preferred_languages = list(languages) if languages is not None else []
    session_state_key = self._get_session_state_key()
    if preferred_languages:
        st.session_state[session_state_key] = preferred_languages
    else:
        st.session_state.pop(session_state_key, None)