i18nco - 国际化
提供了管理国际化（i18n）翻译的接口。
Internationalization
于 i18nco.internationalization 中定义，可在 i18nco 中直接访问。
此类提供了管理国际化（i18n）翻译的接口。
(method) ctrl_set_locale
(method) def ctrl_set_locale(
first_language: LocaleCode | None = None,
second_language: LocaleCode | None = None
) -> None设置语言偏好的区域设置。
您可以设置两种语言：主要语言 (first_language) 和次要语言 (second_language)。当主要语言中没有有效的翻译时，将使用次要语言。
参数
first_language(LocaleCode, 可选)None
要使用的主要语言。如果为None，则保留现有的主要语言。second_language(LocaleCode，可选)None
要使用的次要语言。如果为None，则保留现有的次要语言。
引发
TypeError
如果first_language或second_language不是LocaleCode或None。
示例
仅设置主要语言：
>>> obj.ctrl_set_locale(zh_CN)仅设置次要语言：
>>> obj.ctrl_set_locale(second_language=zh_CN)同时设置主要语言和次要语言：
>>> obj.ctrl_set_locale(zh_CN, en_US)(method) ctrl_get_locale
(method) def ctrl_get_locale() -> Tuple[LocaleCode, LocaleCode]获取当前语言环境设置。
此方法返回一个包含当前主要和次要语言环境代码的元组。主要语言环境是首选语言，而次要语言环境则在主要语言没有翻译时用作后备。
返回
Tuple[LoaleCode, LocaleCode]
一个元组，其中第一个元素是主要语言环境，第二个元素是次要语言环境。
示例
获取当前语言环境设置：
>>> primary, secondary = obj.ctrl_get_locale()
>>> print(primary, secondary)
LocaleCode("en_US") LocaleCode("zh_CN")(method) ctrl_available_locales
(method) def ctrl_available_locales() -> List[LocaleCode]获取当前对象支持的语言列表。
此方法返回当前对象支持的语言列表。每种语言都表示为 LocaleCode 对象。该列表可用于确定可用的本地化选项。
返回
List[LocaleCode]
支持的语言列表，其中每一项都是一个 LocaleCode 对象。
示例
获取支持的语言列表：
>>> available_languages = obj.ctrl_available_locales()
>>> print(available_languages)
[LocaleCode("en_US"), LocaleCode("zh_CN"), LocaleCode("ru_RU")](method) ctrl_set_translation
(method) def ctrl_set_translation(
locale: LocaleCode | None = None,
key: TextKey | None = None,
text: str | None = None
) -> None设置或删除指定语言键的翻译文本。
此方法允许您设置或删除特定键和语言的翻译。如果文本为 None，则将删除指定键的翻译。如果键为 None，则将删除指定语言的所有翻译。
参数
locale(LocaleCode，可选)None
要设置或删除翻译的语言。如果为None，则将使用first_language（先前设置的）。key(TextKey，可选)None
要设置或删除的翻译的键。如果为None，则将删除指定语言的所有翻译。text(str，可选)None
要为翻译设置的文本。如果为None，则将删除指定键的翻译。
引发
TypeError
如果输入类型不正确。
示例
为特定键和语言设置翻译：
>>> obj.ctrl_set_translation(LocaleCode("en_US"), "welcome_message", "Welcome!")删除特定键的翻译：
>>> obj.ctrl_set_translation(LocaleCode("en_US"), "welcome_message")删除特定语言的所有翻译：
>>> obj.ctrl_set_translation(LocaleCode("en_US"))使用默认 first_language 设置翻译：
>>> obj.ctrl_set_translation(None, "welcome_message", "欢迎！"）(method) ctrl_translation
(method) def ctrl_translation(
key: TextKey,
locale: LocaleCode | None = None
) -> I18nString获取指定语言键的翻译文本。
此方法检索指定语言中给定键的翻译文本。如果提供了 locale 参数，将获取该特定语言的翻译。
如果未找到指定键的翻译，则将返回包含键本身的 I18nString 对象。
参数
key(TextKey)
要检索的翻译文本的键。locale(LocaleCode，可选)None
要检索翻译的语言。
返回
I18nString
指定键和语言的翻译文本。如果未找到翻译，则将返回包含键本身的I18nString对象。
引发
TypeError
如果输入类型不正确。
示例
获取特定键和语言的翻译：
>>> translation = obj.ctrl_translation("welcome_message", LocaleCode("en_US"))
>>> print(translation)
"Welcome!"获取不指定语言环境的翻译（使用默认或后备语言）：
>>> translation = obj.ctrl_translation("welcome_message")
>>> print(translation)
"欢迎！"获取不存在的键的翻译：
>>> translation = obj.ctrl_translation("unknown_key")
>>> print(translation)
"unknown_key" # 将键本身作为 I18nString 对象返回。(method) __getattribute__
(method) def __getattribute__(
__name: str,
/
) -> I18nString覆盖默认属性访问行为以支持动态翻译查找。
此方法拦截 Internationalization 实例上的属性访问。如果请求的属性名称以下划线 (_) 或前缀 ctrl_ 开头，则委托给默认属性访问行为（通过 super().__getattribute__）。否则，它将属性名称视为翻译键并返回表示翻译文本的 I18nString 实例。
参数
__name(str)
正在访问的属性的名称。
返回
I18nString
如果属性名称是翻译键，则返回表示翻译文本的I18nString实例。否则，照常返回属性值。
示例
>>> i18n = Internationalization()
>>> i18n.ctrl_set_translation(LocaleCode("en_US"), "welcome_message", "Welcome!")
>>> translation = i18n.welcome_message # 通过属性访问
>>> print(translation)
"Welcome!"
>>> i18n.ctrl_set_translation(LocaleCode("en_US"), "greeting.hello", "Hello!")
>>> translation = i18n.greeting.hello # 嵌套键访问
>>> print(translation)
"Hello!"I18nString
于 i18nco.internationalization 中定义，可在 i18nco 中直接访问。
用于处理国际化 (i18n) 文本的专用字符串类。
此类扩展了内置的 str 类，以支持动态翻译查找和基于属性的嵌套翻译键访问。它旨在与 Internationalization 类配合使用，以提供无缝的多语言支持。
(method) __getattr__
(method) def __getattr__(
__name: str,
/
) -> I18nString动态解析嵌套翻译键。
此方法允许使用点符号（例如"welcome.message"）访问嵌套翻译键。如果当前 _keywords_ 不为空，它会将新键附加到现有路径。
参数
__name(str)
要解析的属性名称（翻译键）。
返回
I18nString
表示已解析翻译的新I18nString实例。
示例
参考 Internationalization 类的 __getattribute__ 方法。
I18nControl
于 i18nco.i18ncontrol 中定义，可在 i18nco 中直接访问。
(class) I18nControl
(method) def __init__(i18n: Internationalization | None = None) -> None初始化 I18nControl 实例。
I18nControl 是 Internationalization 的扩展控制器，提供更方便的方式来管理国际化内容。如果未提供 Internationalization 对象，则会自动创建一个新实例。
参数
i18n(Internationalization，可选)None
要使用的Internationalization对象。如果为None，则会自动创建一个新实例。
引发
TypeError
如果提供的i18n不是Internationalization的实例。
示例
使用现有的 Internationalization 对象进行初始化：
>>> i18n = Internationalization()
>>> controller = I18nControl(i18n)不使用 Internationalization 对象进行初始化（将创建一个新实例）：
>>> controller = I18nControl()(method) set_translation
(method) def set_translation(
locale: LocaleCode | List[LocaleCode] | None = None,
key: TextKey | None = None,
text: str | None = None
) -> None设置或删除指定语言键的翻译文本。
此方法允许您设置或删除特定键和语言的翻译。如果文本为 None，则将删除指定键的翻译。如果键为 None，则将删除指定语言的所有翻译。
参数
locale(LocaleCode，List[LocaleCode]，可选)None
要设置或删除翻译的语言。如果为 None，则将使用 first_language（先前设置的）。key(TextKey，可选)None
要设置或删除的翻译的键。如果为 None，则将删除指定语言的所有翻译。text(str，可选)None
要为翻译设置的文本。如果为 None，则将删除指定键的翻译。
引发
TypeError
如果输入类型不正确。
示例
为特定键和语言设置翻译：
>>> obj.set_translation(LocaleCode("en_US"), "welcome_message", "Welcome!")为多种语言设置翻译：
>>> obj.set_translation([LocaleCode("en_US"), LocaleCode("zh_CN")], "welcome_message", "Welcome!")删除特定键的翻译：
>>> obj.set_translation(LocaleCode("en_US"), "welcome_message", None)删除特定语言的所有翻译：
>>> obj.set_translation(LocaleCode("en_US"), None, None)使用默认 first_language 设置翻译：
>>> obj.set_translation(None, "welcome_message", "Welcome!")(method) translation
参考 Internationalization.ctrl_translation 。
(method) set_locale
(method) def set_locale(
first_language: LocaleCode | None = None,
second_language: LocaleCode | None = None,
auto_adjust: bool = False
) -> None设置语言偏好的区域设置。
您可以设置两种语言：主要语言 (first_language) 和次要语言 (second_language)。当主要语言中没有有效的翻译时，将使用次要语言。默认情况下，次要语言会根据主要语言自动调整。
参数
first_language(LocaleCode，可选)None
要使用的主要语言。如果为None，则保留现有的主要语言。second_language(LocaleCode，可选)None
要使用的次要语言。如果为None，则次要语言会根据主要语言自动调整。auto_adjust(bool)True
是否根据主要语言自动调整次要语言。如果明确设置了second_language，则此参数无效。
引发
TypeError
如果first_language或second_language不是LocaleCode或None。
示例
仅设置主要语言：
>>> obj.set_locale(zh_CN, auto_adjust=False)仅设置次要语言：
>>> obj.set_locale(second_language=zh_CN)同时设置主要语言和次要语言：
>>> obj.set_locale(en_US, zh_CN)设置主要语言并自动调整次要语言：
>>> obj.set_locale(zh_CN)根据现有主要语言自动调整次要语言：
>>> obj.set_locale()(method) get_locale
参考 Internationalization.ctrl_get_locale 。
(method) available_locales
参考 Internationalization.ctrl_available_locales 。
(method) load_lang_content
(method) def load_lang_content(
content: str,
locale: LocaleCode | None = None,
superiors: str | None = None
) -> None从字符串加载语言内容。
此方法解析提供的语言文件内容并将其加载到当前对象中。如果指定了语言环境，则内容将与该语言环境相关联；否则，将使用默认语言环境。
superiors 参数允许您为内容中的所有键指定默认前缀。
参数
content(str)
要加载的语言文件的内容。locale(LocaleCode，可选)None
与内容关联的语言环境。如果为 None，则将使用默认语言环境。superiors(str，可选)None
要添加到内容中所有键的默认前缀。
引发
TypeError
如果locale不是LocaleCode的实例或superiors不是字符串。
示例
为特定语言环境加载内容：
>>> content = '''
... welcome = Welcome!
... '''
>>> obj.load_lang_content(content, LocaleCode("en_US"))
>>> obj.translation("welcome")
"Welcome!"使用默认前缀加载内容：
>>> content = '''
... welcome = Welcome!
... '''
>>> obj.load_lang_content(content, superiors="app")
>>> obj.translation("app.welcome")
"Welcome!"使用默认前缀加载内容并使用 #define 覆盖它：
>>> content = '''
... #define superiors custom
... welcome = Welcome!
... '''
>>> obj.load_lang_content(content, superiors="app")
>>> obj.t
ranslation("custom.welcome")
"Welcome!"(method) load_lang
(method) def load_lang(
file_path: str,
locale: LocaleCode | None = None,
superiors: str | None = None,
*,
encoding: str = DEFAULT_ENCODING
) -> None从文件加载语言内容。
此方法读取语言文件的内容并将其加载到当前对象中。如果指定了语言环境，则内容将与该语言环境相关联；否则，将使用默认语言环境。
superiors 参数允许您为内容中的所有键指定默认前缀。
参数
file_path(str)
要加载的语言文件的路径。locale(LocaleCode，可选)None
与内容关联的语言环境。如果为None，则将使用默认语言环境。superiors(str，可选)None
要添加到内容中所有键的默认前缀。encoding(str，可选)DEFAULT_ENCODING
读取文件时使用的编码。默认为DEFAULT_ENCODING。
引发
FileNotFoundError
如果指定的文件不存在。ValueError
如果文件内容为空或无效。TypeError
如果 locale 不是 LocaleCode 的实例或 superiors 不是字符串。
示例
加载特定语言环境的内容：
>>> obj.load_lang("path/to/lang_file.txt", LocaleCode("en_US"))加载具有默认前缀的内容：
>>> obj.load_lang("path/to/lang_file.txt", superiors="app")加载具有自定义编码的内容：
>>> obj.load_lang("path/to/lang_file.txt", encoding="utf-16")(method) load_csv_i18n
(method) def load_csv_i18n(
file_path: str,
*,
encoding: str = DEFAULT_ENCODING
) -> None从 CSV 文件加载国际化内容。
此方法读取 CSV 文件的内容并将其加载到当前对象中。CSV 文件必须有一个标题行，其中至少包含三列：语言环境、键和值。每行代表一个翻译条目。
参数
file_path(str)
要加载的 CSV 文件的路径。encoding(str，可选)DEFAULT_ENCODING
读取文件时使用的编码。默认为 DEFAULT_ENCODING。
引发
FileNotFoundError
如果指定的文件不存在。ValueError
如果文件内容为空、无效或格式不正确。UnicodeDecodeError
如果无法使用指定的编码解码文件。
示例
从 CSV 文件加载内容：
>>> obj.load_csv_i18n("path/to/translations.csv")从具有自定义编码的 CSV 文件加载内容：
>>> obj.load_csv_i18n("path/to/translations.csv", encoding="utf-16")示例 CSV 文件格式：
>>> locale,key,value
... en_US,greeting,Hello
... zh_CN,greeting,你好(method) load_dict
(method) def load_dict(
dictionary: Dict[TextKey, str],
locale: LocaleCode,
superiors: str | None = None
) -> None从字典中加载翻译内容。
此方法将字典中的翻译键值对加载到当前对象中。翻译将与指定的语言环境相关联。如果提供了 superiors，它将用作所有键的默认前缀。
参数
dictionary(Dict[TextKey, str])
包含翻译键值对的字典。locale(LocaleCode)
与翻译关联的语言环境。superiors(str，可选)
添加到所有键的默认前缀。如果键以 #define 为前缀，它将覆盖此设置。
引发
ValueError
如果字典为空或包含无效数据。TypeError
如果locale不是LocaleCode的实例或superiors不是字符串。
示例
加载特定语言环境的翻译：
>>> Translations = {"greeting": "Hello", "farewell": "Goodbye"}
>>> obj.load_dict(translations, LocaleCode("en_US"))加载带有默认前缀的翻译：
>>> Translations = {"greeting": "Hello", "farewell": "Goodbye"}
>>> obj.load_dict(translations, LocaleCode("en_US"), Superiors="app")(method) load_json
(method) def load_json(
file_path: str,
locale: LocaleCode | None = None,
*,
encoding: str = DEFAULT_ENCODING
) -> None从 JSON 文件加载翻译内容。
此方法读取 JSON 文件的内容并将其加载到当前对象中。如果指定了语言环境，则内容将与该语言环境相关联；否则，将使用默认语言环境。
JSON 文件应格式化为字典，其中键是翻译键，值是翻译文本。
参数
file_path(str)
要加载的 JSON 文件的路径。locale(LocaleCode，可选)
与内容关联的语言环境。如果为None，则将使用默认语言环境。encoding(str，可选)
读取文件时使用的编码。默认为DEFAULT_ENCODING。
引发
FileNotFoundError
如果指定的文件不存在。ValueError
如果文件内容为空、无效或格式不正确。TypeError
如果locale不是LocaleCode的实例。json.JSONDecodeError
如果文件内容不是有效的 JSON。
示例
加载特定语言环境的内容：
>>> obj.load_json("path/to/translations.json", LocaleCode('en_US'))加载内容而不指定语言环境（使用默认语言环境）：
>>> obj.load_json("path/to/translations.json")加载具有自定义编码的内容：
>>> obj.load_json("path/to/translations.json", encoding="utf-16")(method) load_json_i18n
(method) def load_json_i18n(
file_path: str,
*,
encoding: str = DEFAULT_ENCODING
) -> None从 JSON 文件加载国际化内容。
此方法读取 JSON 文件的内容并将其加载到当前对象中。JSON 文件应格式化为字典，其中键是语言环境，值是翻译键值对的字典。
参数
file_path(str)
要加载的 JSON 文件的路径。encoding(str，可选)
读取文件时使用的编码。默认为DEFAULT_ENCODING。
引发
FileNotFoundError
如果指定的文件不存在。ValueError
如果文件内容为空、无效或格式不正确。json.JSONDecodeError
如果文件内容不是有效的 JSON。
示例
从 JSON 文件加载内容：
>>> obj.load_json_i18n("path/to/translations.json")从具有自定义编码的 JSON 文件加载内容：
>>> obj.load_json_i18n("path/to/translations.json", encoding="utf-16")示例 JSON 文件格式：
>>> {
... "en_US": {
... "greeting": "Hello",
... "farewell": "Goodbye"
... },
... "zh_CN": {
... "greeting": "你好",
... "farewell": "再见"
... }
... }(method) auto_load
(method) def auto_load(
path: str,
*,
locale: LocaleCode | None = None
) -> None自动从目录中加载所有语言文件。
此方法扫描指定目录并加载所有支持的语言文件（例如 .lang、.json、.csv）。行为取决于是否指定了 locale 参数：
- 如果指定了
locale：
- 目录应包含名称中不包含语言环境代码的文件。
- 所有文件都将与指定的语言环境相关联。
- 示例结构：
path ├── xxx.lang ├── xxx.lang ├── xxx.json └── xxx.csv
- 如果未指定
locale：
- 目录可以采用以下方式之一进行构建：
- 平面结构：文件名称中包含语言环境代码（例如 zh_CN.lang）。
path ├── zh_CN.lang ├── en_US.lang ├── ru_RU.lang ├── zh_CN.json └── xxx.csv - 嵌套结构：文件被组织到以语言环境代码命名的子目录中。
path ├── zh_CN │ ├── xxx.lang │ ├── xxx.lang │ └── xxx.json └── en_US ├── xxx.lang ├── xxx.lang └── xxx.json - 语言环境将从文件名或子目录名称推断出来。
- 平面结构：文件名称中包含语言环境代码（例如 zh_CN.lang）。
参数
path(str)
包含语言文件的目录的路径。locale(LocaleCode，可选)None
与加载内容关联的语言环境。如果为None，则语言环境将从文件名或子目录名称推断出来。
引发
FileNotFoundError
如果指定的目录不存在。ValueError
如果目录为空、不包含受支持的语言文件或文件或目录名称无效。TypeError
如果locale不是LocaleCode的实例。
示例
加载特定语言环境的文件：
>>> obj.auto_load("path/to/directory", locale=LocaleCode("en_US"))加载文件并从文件名推断语言环境（平面结构）：
>>> obj.auto_load("path/to/flat_directory")加载文件并从子目录名称推断语言环境（嵌套结构）：
>>> obj.auto_load("path/to/nested_directory")