Skip to content

Internationalization Support

This section provides documentation for the internationalization (i18n) features of Flask-X-OpenAPI-Schema.

Internationalization support for OpenAPI metadata.

I18nStr

A string class that supports internationalization.

This class allows you to define strings in multiple languages and automatically returns the appropriate string based on the current language setting.

Parameters:

Name Type Description Default
strings dict[str, str] | str

Either a dictionary mapping language codes to strings, or a single string

 required
default_language str

The default language to use if the requested language is not available

 'en-US'

Examples:

>>> from flask_x_openapi_schema import I18nStr
>>> greeting = I18nStr({"en-US": "Hello", "zh-Hans": "你好", "ja-JP": "こんにちは"})
>>> str(greeting)
'Hello'
>>> greeting.get("zh-Hans")
'你好'
>>> # @openapi_metadata(
>>> #     summary=I18nStr({
>>> #         "en-US": "Get an item",
>>> #         "zh-Hans": "获取一个项目"
>>> #     })
>>> # )
>>> # def get(self, item_id):
>>> #     pass
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
 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
class I18nStr:
    """A string class that supports internationalization.

    This class allows you to define strings in multiple languages and automatically
    returns the appropriate string based on the current language setting.

    Args:
        strings: Either a dictionary mapping language codes to strings, or a single string
        default_language: The default language to use if the requested language is not available

    Examples:
        >>> from flask_x_openapi_schema import I18nStr
        >>> greeting = I18nStr({"en-US": "Hello", "zh-Hans": "你好", "ja-JP": "こんにちは"})
        >>> str(greeting)
        'Hello'
        >>> greeting.get("zh-Hans")
        '你好'
        >>> # @openapi_metadata(
        >>> #     summary=I18nStr({
        >>> #         "en-US": "Get an item",
        >>> #         "zh-Hans": "获取一个项目"
        >>> #     })
        >>> # )
        >>> # def get(self, item_id):
        >>> #     pass

    """

    __slots__ = ("default_language", "strings")

    @classmethod
    def __get_pydantic_core_schema__(cls, _source_type: Any, _handler: Any) -> CoreSchema:
        """Generate a pydantic core schema for I18nString.

        Args:
            _source_type: Source type (unused)
            _handler: Handler (unused)

        Returns:
            CoreSchema: A pydantic core schema for I18nString

        """
        return core_schema.is_instance_schema(cls)

    SUPPORTED_LANGUAGES: ClassVar[list[str]] = [
        "en-US",
        "zh-Hans",
        "zh-Hant",
        "pt-BR",
        "es-ES",
        "fr-FR",
        "de-DE",
        "ja-JP",
        "ko-KR",
        "ru-RU",
        "it-IT",
        "uk-UA",
        "vi-VN",
        "ro-RO",
        "pl-PL",
        "hi-IN",
        "tr-TR",
        "fa-IR",
        "sl-SI",
        "th-TH",
    ]

    def __init__(
        self,
        strings: dict[str, str] | str,
        default_language: str = "en-US",
    ) -> None:
        """Initialize an I18nString.

        Args:
            strings: Either a dictionary mapping language codes to strings,
                    or a single string (which will be used for all languages)
            default_language: The default language to use if the requested language is not available

        """
        self.default_language = default_language

        if isinstance(strings, str):
            self.strings = dict.fromkeys(self.SUPPORTED_LANGUAGES, strings)

            self.strings[self.default_language] = strings
        else:
            self.strings = strings

            if self.default_language not in self.strings:
                if self.strings:
                    self.strings[self.default_language] = next(iter(self.strings.values()))
                else:
                    self.strings[self.default_language] = ""

    def get(self, language: str | None = None) -> str:
        """Get the string in the specified language.

        Args:
            language: The language code to get the string for.
                     If None, uses the current language.

        Returns:
            str: The string in the requested language, or the default language if not available

        """
        if language is None:
            language = get_current_language()

        if language in self.strings:
            return self.strings[language]

        return self.strings[self.default_language]

    def __str__(self) -> str:
        """Get the string in the current language.

        Returns:
            str: The string in the current language

        """
        return self.get()

    def __repr__(self) -> str:
        """Get a string representation of the I18nString.

        Returns:
            str: A string representation of the I18nString

        """
        return f"I18nString({self.strings})"

    def __eq__(self, other: object) -> bool:
        """Compare this I18nString with another object.

        Args:
            other: The object to compare with

        Returns:
            bool: True if the objects are equal, False otherwise

        """
        if isinstance(other, I18nStr):
            return self.strings == other.strings
        if isinstance(other, str):
            return str(self) == other
        return False

    def __hash__(self) -> int:
        """Get a hash value for the I18nString.

        This is needed for using I18nString as a dictionary key or in sets.

        Returns:
            int: A hash value for the I18nString

        """
        return hash((frozenset(self.strings.items()), self.default_language))

    @classmethod
    def create(cls, **kwargs: Any) -> "I18nStr":
        """Create an I18nString from keyword arguments.

        This is a convenience method for creating an I18nString with named language parameters.

        Args:
            **kwargs: Keyword arguments where the keys are language codes (with underscores
                     instead of hyphens) and the values are the strings in those languages

        Returns:
            I18nStr: An I18nString instance

        Examples:
            >>> from flask_x_openapi_schema.i18n.i18n_string import I18nStr
            >>> greeting = I18nStr.create(en_US="Hello", zh_Hans="你好", ja_JP="こんにちは")
            >>> str(greeting)
            'Hello'

        """
        strings = {k.replace("_", "-"): v for k, v in kwargs.items()}
        return cls(strings)
__eq__(other)

Compare this I18nString with another object.

Parameters:

Name Type Description Default
other object

The object to compare with

 required

Returns:

Name Type Description
bool bool

True if the objects are equal, False otherwise
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
def __eq__(self, other: object) -> bool:
    """Compare this I18nString with another object.

    Args:
        other: The object to compare with

    Returns:
        bool: True if the objects are equal, False otherwise

    """
    if isinstance(other, I18nStr):
        return self.strings == other.strings
    if isinstance(other, str):
        return str(self) == other
    return False
__get_pydantic_core_schema__(_source_type, _handler) classmethod

Generate a pydantic core schema for I18nString.

Parameters:

Name Type Description Default
_source_type Any

Source type (unused)

 required
_handler Any

Handler (unused)

 required

Returns:

Name Type Description
CoreSchema CoreSchema

A pydantic core schema for I18nString
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
82
83
84
85
86
87
88
89
90
91
92
93
94
@classmethod
def __get_pydantic_core_schema__(cls, _source_type: Any, _handler: Any) -> CoreSchema:
    """Generate a pydantic core schema for I18nString.

    Args:
        _source_type: Source type (unused)
        _handler: Handler (unused)

    Returns:
        CoreSchema: A pydantic core schema for I18nString

    """
    return core_schema.is_instance_schema(cls)
__hash__()

Get a hash value for the I18nString.

This is needed for using I18nString as a dictionary key or in sets.

Returns:

Name Type Description
int int

A hash value for the I18nString
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
200
201
202
203
204
205
206
207
208
209
def __hash__(self) -> int:
    """Get a hash value for the I18nString.

    This is needed for using I18nString as a dictionary key or in sets.

    Returns:
        int: A hash value for the I18nString

    """
    return hash((frozenset(self.strings.items()), self.default_language))
__init__(strings, default_language='en-US')

Initialize an I18nString.

Parameters:

Name Type Description Default
strings dict[str, str] | str

Either a dictionary mapping language codes to strings, or a single string (which will be used for all languages)

 required
default_language str

The default language to use if the requested language is not available

 'en-US'
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
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
def __init__(
    self,
    strings: dict[str, str] | str,
    default_language: str = "en-US",
) -> None:
    """Initialize an I18nString.

    Args:
        strings: Either a dictionary mapping language codes to strings,
                or a single string (which will be used for all languages)
        default_language: The default language to use if the requested language is not available

    """
    self.default_language = default_language

    if isinstance(strings, str):
        self.strings = dict.fromkeys(self.SUPPORTED_LANGUAGES, strings)

        self.strings[self.default_language] = strings
    else:
        self.strings = strings

        if self.default_language not in self.strings:
            if self.strings:
                self.strings[self.default_language] = next(iter(self.strings.values()))
            else:
                self.strings[self.default_language] = ""
__repr__()

Get a string representation of the I18nString.

Returns:

Name Type Description
str str

A string representation of the I18nString
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
175
176
177
178
179
180
181
182
def __repr__(self) -> str:
    """Get a string representation of the I18nString.

    Returns:
        str: A string representation of the I18nString

    """
    return f"I18nString({self.strings})"
__str__()

Get the string in the current language.

Returns:

Name Type Description
str str

The string in the current language
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
166
167
168
169
170
171
172
173
def __str__(self) -> str:
    """Get the string in the current language.

    Returns:
        str: The string in the current language

    """
    return self.get()
create(**kwargs) classmethod

Create an I18nString from keyword arguments.

This is a convenience method for creating an I18nString with named language parameters.

Parameters:

Name Type Description Default
**kwargs Any

Keyword arguments where the keys are language codes (with underscores instead of hyphens) and the values are the strings in those languages

 {}

Returns:

Name Type Description
I18nStr I18nStr

An I18nString instance

Examples:

>>> from flask_x_openapi_schema.i18n.i18n_string import I18nStr
>>> greeting = I18nStr.create(en_US="Hello", zh_Hans="你好", ja_JP="こんにちは")
>>> str(greeting)
'Hello'
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
@classmethod
def create(cls, **kwargs: Any) -> "I18nStr":
    """Create an I18nString from keyword arguments.

    This is a convenience method for creating an I18nString with named language parameters.

    Args:
        **kwargs: Keyword arguments where the keys are language codes (with underscores
                 instead of hyphens) and the values are the strings in those languages

    Returns:
        I18nStr: An I18nString instance

    Examples:
        >>> from flask_x_openapi_schema.i18n.i18n_string import I18nStr
        >>> greeting = I18nStr.create(en_US="Hello", zh_Hans="你好", ja_JP="こんにちは")
        >>> str(greeting)
        'Hello'

    """
    strings = {k.replace("_", "-"): v for k, v in kwargs.items()}
    return cls(strings)
get(language=None)

Get the string in the specified language.

Parameters:

Name Type Description Default
language str | None

The language code to get the string for. If None, uses the current language.

 None

Returns:

Name Type Description
str str

The string in the requested language, or the default language if not available
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
def get(self, language: str | None = None) -> str:
    """Get the string in the specified language.

    Args:
        language: The language code to get the string for.
                 If None, uses the current language.

    Returns:
        str: The string in the requested language, or the default language if not available

    """
    if language is None:
        language = get_current_language()

    if language in self.strings:
        return self.strings[language]

    return self.strings[self.default_language]

get_current_language()

Get the current language for the current thread.

This function returns the language code that is currently set for the current thread. The language code is used for internationalization of strings in the OpenAPI schema.

Returns:

Name Type Description
str str

The current language code (e.g., "en-US", "zh-Hans")

Examples:

>>> from flask_x_openapi_schema import get_current_language
>>> get_current_language()
'en-US'
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def get_current_language() -> str:
    """Get the current language for the current thread.

    This function returns the language code that is currently set for the current thread.
    The language code is used for internationalization of strings in the OpenAPI schema.

    Returns:
        str: The current language code (e.g., "en-US", "zh-Hans")

    Examples:
        >>> from flask_x_openapi_schema import get_current_language
        >>> get_current_language()
        'en-US'

    """
    return _current_language.get()

set_current_language(language)

Set the current language for the current thread.

This function sets the language code for the current thread. This affects how internationalized strings are displayed in the OpenAPI schema and in responses.

Parameters:

Name Type Description Default
language str

The language code to set (e.g., "en-US", "zh-Hans")

 required

Examples:

>>> from flask_x_openapi_schema import set_current_language
>>> set_current_language("zh-Hans")
Source code in src/flask_x_openapi_schema/i18n/i18n_string.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def set_current_language(language: str) -> None:
    """Set the current language for the current thread.

    This function sets the language code for the current thread. This affects how
    internationalized strings are displayed in the OpenAPI schema and in responses.

    Args:
        language: The language code to set (e.g., "en-US", "zh-Hans")

    Examples:
        >>> from flask_x_openapi_schema import set_current_language
        >>> set_current_language("zh-Hans")

    """
    _current_language.set(language)