Система международной локализации (i18n)
Tip
Когда нужно это читать: при необходимости многоязычного контента, регистрации переводов или определения языка. Если не нужно, пропустите, это не повлияет на использование других функций.
Начиная с версии ErisPulse v2.5.0, встроенная поддержка международной локализации. Ядро фреймворка и интерфейс CLI могут автоматически переключать отображаемый текст в соответствии с языком вашей системы, а также поддерживают регистрацию переводов внешними модулями.
Поддерживаемые языки
| Язык | Код | Описание |
|---|---|---|
| 简体中文 | zh-CN |
Основной язык (оригинальный язык фреймворка) |
| 繁體中文 | zh-TW |
Традиционный китайский (Гонконг/Макао/Тайвань) |
| English | en |
Английский (язык по умолчанию) |
| 日本語 | ja |
Японский |
| Русский | ru |
Русский |
Быстрый опыт
Через переменные окружения
# Windows PowerShell
$env:ERISPULSE_LANG = "en"
epsdk run
# macOS / Linux
ERISPULSE_LANG=ja epsdk run
Через файл конфигурации
В файле config/config.toml добавьте:
[ErisPulse.i18n]
language = "zh-TW"
Установка значения "auto" (значение по умолчанию) включает автоматическое определение языка системы.
В коде вручную
from ErisPulse import i18n
# Ручная установка языка
i18n.set_language("en")
print(i18n.get_language()) # "en"
# Сброс на автоматическое определение
i18n.reset_language()
Механизм определения языка
Фреймворк определяет язык пользователя по следующему приоритету:
- Переменная окружения
ERISPULSE_LANG— наивысший приоритет, используется для тестирования и временного переключения - Windows API —
GetUserDefaultLocaleName(только Windows, не подвергается влиянию таких инструментов, как Git Bash, которые могут переопределитьLANG) - Переменные окружения —
LANGUAGE>LC_ALL>LC_MESSAGES>LANG(стандарт Unix/macOS) - Системная локаль —
locale.getlocale()/locale.getdefaultlocale() - Обратный путь — en (английский)
Принцип ближайшего соответствия
При обнаружении языка, не являющегося точным совпадением, используется принцип ближайшего соответствия:
zh-TW,zh-HK,zh-MO,zh-Hant→ Традиционный китайский- Все остальные
zh-*(например,zh-CN,zh-SG) → Упрощённый китайский en-US,en-GB,en-AUи т.д. → Английскийja-JP→ Японскийru-RU→ Русский- Нераспознанные языки → Упрощённый китайский (обратный путь)
Использование i18n в модулях
Вы можете зарегистрировать переводы для своих модулей, чтобы сделать их также поддерживаемыми в нескольких языках.
Рекомендуемый способ: объявление ключей перевода через I18nClass (v2.7.0+)
Начиная с версии v2.7.0, модули/адаптеры могут объявлять ключи перевода, как объявление ConfigClass, с помощью вложенного класса I18nClass. Фреймворк автоматически зарегистрирует все объявленные ключи перевода при загрузке, без необходимости вызывать i18n.register() вручную.
from dataclasses import dataclass, field
from ErisPulse.Core.Bases import BaseConfig, BaseI18n, BaseModule, I18nKey
class MyModule(BaseModule):
# Класс конфигурации (опционально)
@dataclass
class ConfigClass(BaseConfig):
welcome_msg: str = field(
default="欢迎",
metadata={
# Здесь используется i18n-ключ mymodule.welcome_msg
"description": {"i18n": "mymodule.welcome_msg", "default": "欢迎消息"},
},
)
# Класс набора ключей перевода (опционально)
# Объявленные ключи будут автоматически зарегистрированы фреймворком, с приоритетом над генерацией дефолтных значений ConfigClass
class I18nClass(BaseI18n):
# Имя атрибута автоматически объединяется в полный путь ключа: <имя модуля>.<имя атрибута>
welcome_msg: I18nKey = I18nKey(
default="Welcome Message", # Языко-независимый резервный вариант, не регистрируется ни в один язык
zh_CN="欢迎消息",
en="Welcome Message",
ja="ウェルカムメッセージ",
ru="Приветственное сообщение",
zh_TW="歡迎訊息",
)
# Другие ключи перевода, используемые в бизнес-логике
hello: I18nKey = I18nKey(
default="Hello, {name}!",
zh_CN="你好,{name}!",
zh_TW="你好,{name}!",
en="Hello, {name}!",
ja="こんにちは、{name}!",
ru="Привет, {name}!",
)
# Можно явно указать полный путь ключа (без использования имени атрибута)
custom: I18nKey = I18nKey(
key="mymodule.deep.nested.key",
default="Default text",
zh_CN="默认文本",
zh_TW="預設文本",
en="Default text",
ja="デフォルトテキスト",
ru="Текст по умолчанию",
)
Почему рекомендуется I18nClass?
| Сценарий | Ручная i18n.register() | Декларативный I18nClass |
|---|---|---|
| Описание конфигурации с использованием i18n-ключа | Требуется ручная регистрация, и нужно успеть до генерации конфигурации | Фреймворк автоматически регистрирует до генерации конфигурации |
| Объявление многоязычных переводов | Распространяется по on_load() | Централизовано в классе, легко читается |
| Согласованность именования ключей | Легко допускаются опечатки | Имя атрибута используется как суффикс ключа, IDE может подсказывать |
| Очистка при отключении | Требуется ручная unregister_domain() | Фреймворк использует единый домен для регистрации |
Правила пути ключей I18nClass
- По умолчанию: Используется
<имя регистрации модуля>.<имя атрибута>как полный путь ключа- Пример: Имя модуля
MyModule, атрибутwelcome→ Путь ключаMyModule.welcome
- Пример: Имя модуля
- Явно: Через параметр
I18nKey(key="...")можно указать любой точечный путь- Подходит для глубоко вложенных ключей (например,
mymodule.config.basic.token)
- Подходит для глубоко вложенных ключей (например,
Использование в адаптерах
Адаптеры также поддерживают I18nClass, и способ использования полностью идентичен:
from ErisPulse.Core import BaseAdapter
from ErisPulse.Core.Bases import BaseConfig, BaseI18n, I18nKey
class MyAdapter(BaseAdapter):
@dataclass
class ConfigClass(BaseConfig):
endpoint: str = field(
default="",
metadata={
# Описание конфигурации ссылается на ключ adapter.MyAdapter.endpoint
"description": {"i18n": "MyAdapter.endpoint", "default": "API 地址"},
},
)
class I18nClass(BaseI18n):
# Централизованное объявление ключей перевода, используемых в описании конфигурации и других бизнес-ключах
endpoint: I18nKey = I18nKey(
default="API Endpoint",
zh_CN="API 地址",
zh_TW="API 位址",
en="API Endpoint",
ja="APIアドレス",
ru="API адрес",
)
I18nClass адаптера автоматически регистрируется на этапе __init__ (до генерации шаблона конфигурации), обеспечивая доступность ключей перевода, используемых в описании конфигурации.
Ручная регистрация пользовательских переводов (старый способ)
Если вы не используете I18nClass, вы можете напрямую вызвать i18n.register() для регистрации переводов.
from ErisPulse import i18n
# Регистрация китайского перевода
i18n.register("zh-CN", {
"my_module.welcome": "欢迎使用我的模块!",
"my_module.goodbye": "再见!",
"my_module.hello": "你好,{name}!",
}, domain="my_module")
# Регистрация английского перевода
i18n.register("en", {
"my_module.welcome": "Welcome to my module!",
"my_module.goodbye": "Goodbye!",
"my_module.hello": "Hello, {name}!",
}, domain="my_module")
Использование перевода
from ErisPulse import i18n
# Простой перевод
i18n.t("my_module.welcome") # Автоматически использует текущий язык
# С параметрами форматирования
i18n.t("my_module.hello", name="Alice")
# Указание значения по умолчанию (возвращается, если ключ перевода отсутствует)
i18n.t("my_module.unknown_key", default="默认文本")
Использование в классе модуля
from dataclasses import dataclass, field
from ErisPulse import i18n
from ErisPulse.Core.Bases import BaseConfig, BaseModule
@dataclass
class MyModuleConfig(BaseConfig):
welcome_msg: str = field(
default="欢迎",
metadata={
"description": {"i18n": "my_module.welcome_msg", "default": "欢迎消息"},
"ui": {"widget": "text", "group": "basic", "order": 1},
},
)
class MyModule(BaseModule):
ConfigClass = MyModuleConfig
async def on_load(self, event):
# Динамическое чтение конфигурации (каждый доступ отражает последнее значение)
self.logger.info(self.cfg.welcome_msg)
self.logger.info(i18n.t("my_module.welcome"))
@command("hello")
async def hello_handler(self, event):
name = event.get_user_nickname() or "friend"
await event.reply(i18n.t("my_module.hello", name=name))
async def on_unload(self, event):
pass
Отмена регистрации перевода
# Отмена регистрации всего домена перевода
i18n.unregister_domain("my_module")
Многоязычные поля конфигурации
Начиная с версии v2.5.2, схема конфигурации полностью поддерживает i18n. Все пользовательские текстовые поля могут ссылаться на i18n-ключи, и веб-интерфейс и другие потребители автоматически будут использовать соответствующий текст в зависимости от текущего языка.
Поддерживаемые i18n-поля
| Поле | Расположение | Описание |
|---|---|---|
description |
field metadata | Описание поля |
options[].label |
ui.options |
Метка опций для элемента select |
placeholder |
ui.placeholder |
Заполнитель для поля ввода |
group_labels |
_schema_meta |
Название раздела (заголовок секции в Dashboard) |
Используется единый формат {"i18n": "key", "default": "текст"}, строки без i18n-ключа прозрачно передаются (для обратной совместимости).
Объявление i18n-полей
Все пользовательские текстовые поля поддерживают i18n:
from dataclasses import dataclass, field
from ErisPulse.Core.Bases import BaseConfig
@dataclass
class MyAdapterConfig(BaseConfig):
# i18n для description
token: str = field(
default="",
metadata={
"description": {"i18n": "my_adapter.token", "default": "平台 Token"},
"required": True,
"secret": True,
"ui": {
"widget": "password",
"group": "basic",
"order": 1,
# i18n для placeholder
"placeholder": {"i18n": "my_adapter.token.ph", "default": "请输入 Token"},
},
},
)
# i18n для label опций
mode: str = field(
default="a",
metadata={
"description": {"i18n": "my_adapter.mode", "default": "运行模式"},
"ui": {
"widget": "select",
"group": "basic",
"order": 2,
"options": [
{"label": {"i18n": "my_adapter.mode.a", "default": "模式A"}, "value": "a"},
{"label": {"i18n": "my_adapter.mode.b", "default": "模式B"}, "value": "b"},
],
},
},
)
# i18n для group_labels (название раздела)
_schema_meta = {
"group_labels": {
"basic": {"i18n": "my_adapter.group.basic", "default": "基本设置"},
}
}
default — это резервный текст, отображается, когда перевод не зарегистрирован или поиск не удаётся.
Скрытие секретных данных и проверка конфигурации
Поля, помеченные как "secret": True, автоматически получают защиту от раскрытия (начиная с версии 2.7.0):
- Скрытие при генерации шаблона:
dataclass_to_toml_with_comments()при генерации шаблона конфигурации не записывает реальное значение секретных полей (отображается пустой заполнитель), предотвращая попадание конфиденциальной информации на диск - Общее средство скрытия:
redact_secret(value)заменяет непустое значение на***, пустое значение возвращается без изменений, может использоваться для вывода в логи и т.д.
from ErisPulse.Core.Bases.config_schema import redact_secret
redact_secret("sk-xxxxxx") # '***'
redact_secret("") # ''
Проверка конфигурации (validate_config()) помимо проверки required на непустоту, начиная с версии 2.7.0, поддерживает:
| Проверка | Метаданные | Пример |
|---|---|---|
| Совпадение типа | Тип поля | Ошибка, если в поле int передано строковое значение |
| Ограничение перечисления | ui.options или顶层 options |
Значение должно принадлежать разрешённым опциям |
| Диапазон значений | 顶层 min / max |
metadata={"min": 1, "max": 65535} |
from ErisPulse.Core.Bases.config_schema import validate_config
@dataclass
class C(BaseConfig):
mode: str = field(default="a", metadata={"ui": {"widget": "select", "options": ["a", "b"]}})
port: int = field(default=80, metadata={"min": 1, "max": 65535})
errors = validate_config(C(mode="x", port=70000)) # Две ошибки: перечисление + диапазон
Регистрация перевода конфигурации
Ключи перевода конфигурации и обычные ключи перевода одинаковы, используют i18n.register() для регистрации:
from ErisPulse import i18n
# Регистрация китайского (согласуется с default, но может отличаться)
i18n.register("zh-CN", {
"my_adapter.token": "平台 Token",
}, domain="my_adapter")
# Регистрация английского
i18n.register("en", {
"my_adapter.token": "Platform Token",
}, domain="my_adapter")
Рекомендуемый способ: Использование
I18nClassдля объявления ключей перевода, фреймворк автоматически регистрирует (см. раздел "Рекомендуемый способ" выше), нет необходимости вызыватьi18n.register()илиregister_config_i18n()вручную.
Также предоставлена удобная функция register_config_i18n(), которая автоматически извлекает ключи и регистрирует их из класса конфигурации:
from ErisPulse.Core.Bases.config_schema import register_config_i18n
# Автоматически извлекает description.default как перевод для zh-CN
register_config_i18n(MyAdapterConfig, "zh-CN")
# Ручная передача английского перевода
register_config_i18n(MyAdapterConfig, "en", {
"my_adapter.token": "Platform Token",
})
Как WebUI потребляет
get_config_schema() возвращает схему, в которой словарь i18n передаётся без изменений. Фронтенд WebUI может использовать i18n.t() для разрешения текущего языка.
Если требуется, чтобы серверная часть разрешила текст в строку (например, для возврата клиенту, который не поддерживает i18n), используйте resolve_config_schema(), который разрешит все поля description, options[].label, placeholder, group_labels в текст текущего языка:
from ErisPulse.Core.Bases.config_schema import resolve_config_schema
# Все поля i18n разрешены в текст текущего языка
schema = resolve_config_schema(MyAdapterConfig)
print(schema["fields"]["token"]["description"]) # "平台 Token" или "Platform Token"
print(schema["fields"]["token"]["placeholder"]) # "请输入 Token" или "Enter Token"
print(schema["fields"]["mode"]["options"][0]["label"]) # "模式A" или "Mode A"
print(schema["group_labels"]["basic"]) # "基本设置" или "Basic"
BaseConfig,BotAccountConfig,register_config_i18n(),resolve_config_schema()и другие типы и функции инструментария фактически определены вErisPulse.Core.Bases.config_schema.ErisPulse.runtime.config_schemaсохраняется как совместимый shim, рекомендуется импортировать изErisPulse.Core.Bases(за исключением типов, связанных с i18n-ключами, они находятся вErisPulse.Core.Bases.i18n_schema).
Справочник API
I18nManager
Основные методы
| Метод | Описание |
|---|---|
t(key, default=None, **kwargs) |
Получить текст перевода (gettext() — синоним) |
set_language(lang) |
Ручная установка языка |
get_language() |
Получить текущий язык |
reset_language() |
Сброс на автоматическое определение (и повторное определение среды) |
get_supported_languages() |
Получить список всех поддерживаемых языков |
has_translation(key, lang=None) |
Проверить наличие перевода ключа |
register(lang, translations, domain) |
Зарегистрировать пользовательский перевод |
unregister_domain(domain) |
Удалить все переводы указанного домена |
reload() |
Перезагрузить встроенные переводы и повторно определить язык |
Подробности метода t()
def t(self, key, /, default=None, **kwargs):
key— ключ перевода (только позиционный аргумент, не конфликтует с**kwargsсkey=)default— значение по умолчанию, возвращается, если перевод отсутствует, по умолчаниюNone(возвращается сам ключ)**kwargs— параметры форматирования, используются для заполнения{placeholder}в переводе
Пример:
# Перевод: "greeting": "你好,{name}!欢迎来到{place}。"
i18n.t("greeting", name="Alice", place="ErisPulse")
# Возвращает: "你好,Alice!欢迎来到ErisPulse。"
BaseI18n / I18nKey (декларативные ключи перевода)
Начиная с версии v2.7.0, ErisPulse.Core.Bases предоставляет инструменты декларативного объявления ключей перевода на основе атрибутов класса (рекомендуется импортировать из ErisPulse.Core.Bases):
I18nKey.default— это языко-независимый резервный текст, не регистрируется ни в один язык. Чтобы перевод был активен, необходимо явно передать хотя бы один параметр языка (zh_CN=/en=/ja=и т.д.). Таким образом, разработчики из разных стран могут свободно использовать свой родной язык для заполненияdefault, фреймворк не делает никаких предположений.
| Название | Описание |
|---|---|
I18nKey(default, *, key=None, zh_CN, zh_TW, en, ja, ru) |
Объявление одного ключа перевода, default — резервный текст без привязки к языку |
BaseI18n |
Базовый класс для набора ключей перевода (имя соответствует BaseConfig), подклассы объявляют несколько I18nKey как атрибуты класса |
BaseI18n.register(prefix="", domain="app") |
Метод класса: регистрирует все объявленные ключи в системе i18n |
key |
Алиас I18nKey (более краткая запись) |
Пример использования:
from ErisPulse.Core.Bases import BaseI18n, key
class MyKeys(BaseI18n):
# Упрощённая запись с алиасом
hello = key(
default="Hello",
zh_CN="你好",
zh_TW="你好",
en="Hello",
ja="こんにちは",
ru="Привет",
)
bye = key(
default="Bye",
zh_CN="再见",
zh_TW="再見",
en="Bye",
ja="さようなら",
ru="До свидания",
)
# Использование отдельно (ручная регистрация)
MyKeys.register(prefix="myapp.", domain="myapp")
Доступ через экземпляр SDK
from ErisPulse import sdk
# sdk.i18n и i18n, импортированный напрямую, — это один и тот же объект
sdk.i18n.set_language("en")
print(sdk.i18n.t("core.sdk.init.starting"))
Конфигурация во время выполнения
Чтение i18n-конфигурации через API конфигурации
from ErisPulse.Core.Bases import I18nConfig
from ErisPulse.runtime import get_i18n_config
config = get_i18n_config()
print(config["language"]) # "auto" или код языка
# I18nConfig — это dataclass, может использоваться для генерации шаблона конфигурации
schema = I18nConfig.__dataclass_fields__
Описание конфигурационных параметров
В секции [ErisPulse.i18n] файла config/config.toml:
[ErisPulse.i18n]
# Язык отображения, возможные значения:
# - "auto" — автоматическое определение языка системы (по умолчанию)
# - "zh-CN" — упрощённый китайский
# - "zh-TW" — традиционный китайский
# - "en" — английский
# - "ja" — японский
# - "ru" — русский
language = "auto"
Лучшие практики
Именование ключей перевода
Рекомендуется использовать формат с разделением точкой:
<имя модуля>.<категория>.<описание>
Например: my_module.command.hello_desc, core.adapter.start_failed
Многоязычное покрытие
Не обязательно предоставлять переводы для всех языков сразу; отсутствующие языки автоматически возвращаются к английскому, если английского тоже нет, отображается сам ключ.
Динамический контент
Для динамически генерируемого контента (например, имен пользователей, количества и т.д.) используйте формат {placeholder}:
# Определение перевода
"user_count": "当前在线用户:{count} 人"
# Использование
i18n.t("user_count", count=len(users))
Журналы сообщений
Если ваш модуль использует логгер фреймворка, эти сообщения также будут автоматически использовать текущий язык:
self.logger.info(i18n.t("my_module.startup"))
Отношение к i18n в CLI
CLI имеет независимый модуль международной локализации (ErisPulse.CLI.i18n), полностью развязанный с модулем международной локализации ядра фреймворка.
- Core i18n — используется ядром фреймворка, внешние модули могут регистрировать переводы
- CLI i18n — используется внутренним интерфейсом командной строки, не делится данными перевода с Core
Такая архитектура гарантирует, что изменения в переводах CLI не повлияют на стабильность ядра фреймворка.
Связанные документы
- Добавление многоязычных описаний к полям конфигурации модуля (ConfigClass) → Руководство по конфигурации
- Автоматическая очистка доменов перевода при деактивации модуля → Система собственности (owner)
- Разработка модуля с поддержкой многоязычности с нуля → Руководство по разработке модулей