summaryrefslogtreecommitdiffstats
path: root/sphinx/locale/__init__.py
blob: f464b4cab99ad3daadd9c93a7f8c31533dfae93b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
"""Locale utilities."""

from __future__ import annotations

import locale
import sys
from gettext import NullTranslations, translation
from os import path
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from collections.abc import Iterable
    from typing import Any, Callable


class _TranslationProxy:
    """
    The proxy implementation attempts to be as complete as possible, so that
    the lazy objects should mostly work as expected, for example for sorting.
    """

    __slots__ = '_catalogue', '_namespace', '_message'

    def __init__(self, catalogue: str, namespace: str, message: str) -> None:
        self._catalogue = catalogue
        self._namespace = namespace
        self._message = message

    def __str__(self) -> str:
        try:
            return translators[self._namespace, self._catalogue].gettext(self._message)
        except KeyError:
            # NullTranslations().gettext(self._message) == self._message
            return self._message

    def __dir__(self) -> list[str]:
        return dir(str)

    def __getattr__(self, name: str) -> Any:
        return getattr(self.__str__(), name)

    def __getstate__(self) -> tuple[str, str, str]:
        return self._catalogue, self._namespace, self._message

    def __setstate__(self, tup: tuple[str, str, str]) -> None:
        self._catalogue, self._namespace, self._message = tup

    def __copy__(self) -> _TranslationProxy:
        return _TranslationProxy(self._catalogue, self._namespace, self._message)

    def __repr__(self) -> str:
        try:
            return f'i{self.__str__()!r}'
        except Exception:
            return (
                self.__class__.__name__
                + f'({self._catalogue}, {self._namespace}, {self._message})'
            )

    def __add__(self, other: str) -> str:
        return self.__str__() + other

    def __radd__(self, other: str) -> str:
        return other + self.__str__()

    def __mod__(self, other: str) -> str:
        return self.__str__() % other

    def __rmod__(self, other: str) -> str:
        return other % self.__str__()

    def __mul__(self, other: Any) -> str:
        return self.__str__() * other

    def __rmul__(self, other: Any) -> str:
        return other * self.__str__()

    def __hash__(self) -> int:
        return hash(self.__str__())

    def __eq__(self, other: object) -> bool:
        return self.__str__() == other

    def __lt__(self, string: str) -> bool:
        return self.__str__() < string

    def __contains__(self, char: str) -> bool:
        return char in self.__str__()

    def __len__(self) -> int:
        return len(self.__str__())

    def __getitem__(self, index: int | slice) -> str:
        return self.__str__()[index]


translators: dict[tuple[str, str], NullTranslations] = {}


def init(
    locale_dirs: Iterable[str | None],
    language: str | None,
    catalog: str = 'sphinx',
    namespace: str = 'general',
) -> tuple[NullTranslations, bool]:
    """Look for message catalogs in `locale_dirs` and *ensure* that there is at
    least a NullTranslations catalog set in `translators`. If called multiple
    times or if several ``.mo`` files are found, their contents are merged
    together (thus making ``init`` reentrant).
    """
    translator = translators.get((namespace, catalog))
    # ignore previously failed attempts to find message catalogs
    if translator.__class__ is NullTranslations:
        translator = None

    if language:
        if '_' in language:
            # for language having country code (like "de_AT")
            languages: list[str] | None = [language, language.split('_')[0]]
        else:
            languages = [language]
    else:
        languages = None

    # loading
    # the None entry is the system's default locale path
    for dir_ in locale_dirs:
        try:
            trans = translation(catalog, localedir=dir_, languages=languages)
            if translator is None:
                translator = trans
            else:
                translator.add_fallback(trans)
        except Exception:
            # Language couldn't be found in the specified path
            pass
    if translator is not None:
        has_translation = True
    else:
        translator = NullTranslations()
        has_translation = False
    # guarantee translators[(namespace, catalog)] exists
    translators[namespace, catalog] = translator
    return translator, has_translation


_LOCALE_DIR = path.abspath(path.dirname(__file__))


def init_console(
    locale_dir: str | None = None,
    catalog: str = 'sphinx',
) -> tuple[NullTranslations, bool]:
    """Initialize locale for console.

    .. versionadded:: 1.8
    """
    if locale_dir is None:
        locale_dir = _LOCALE_DIR
    if sys.platform == 'win32':
        language = None
    else:
        try:
            # encoding is ignored
            language, _ = locale.getlocale(locale.LC_MESSAGES)
        except AttributeError:
            # Fallback to the default language in case LC_MESSAGES is not defined.
            language = None
    return init([locale_dir], language, catalog, 'console')


def get_translator(catalog: str = 'sphinx', namespace: str = 'general') -> NullTranslations:
    return translators.get((namespace, catalog), NullTranslations())


def is_translator_registered(catalog: str = 'sphinx', namespace: str = 'general') -> bool:
    return (namespace, catalog) in translators


def get_translation(catalog: str, namespace: str = 'general') -> Callable[[str], str]:
    """Get a translation function based on the *catalog* and *namespace*.

    The extension can use this API to translate the messages on the
    extension::

        import os
        from sphinx.locale import get_translation

        MESSAGE_CATALOG_NAME = 'myextension'  # name of *.pot, *.po and *.mo files
        _ = get_translation(MESSAGE_CATALOG_NAME)
        text = _('Hello Sphinx!')


        def setup(app):
            package_dir = os.path.abspath(os.path.dirname(__file__))
            locale_dir = os.path.join(package_dir, 'locales')
            app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

    With this code, sphinx searches a message catalog from
    ``${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo``.
    The :confval:`language` is used for the searching.

    .. versionadded:: 1.8
    """

    def gettext(message: str) -> str:
        if not is_translator_registered(catalog, namespace):
            # not initialized yet
            return _TranslationProxy(catalog, namespace, message)  # type: ignore[return-value]  # NoQA: E501
        else:
            translator = get_translator(catalog, namespace)
            return translator.gettext(message)

    return gettext


# A shortcut for sphinx-core
#: Translation function for messages on documentation (menu, labels, themes and so on).
#: This function follows :confval:`language` setting.
_ = get_translation('sphinx')
#: Translation function for console messages
#: This function follows locale setting (`LC_ALL`, `LC_MESSAGES` and so on).
__ = get_translation('sphinx', 'console')


# labels
admonitionlabels = {
    'attention': _('Attention'),
    'caution': _('Caution'),
    'danger': _('Danger'),
    'error': _('Error'),
    'hint': _('Hint'),
    'important': _('Important'),
    'note': _('Note'),
    'seealso': _('See also'),
    'tip': _('Tip'),
    'warning': _('Warning'),
}