ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Поддерживаемые языки Быстрый опыт Через переменные окружения Через файл конфигурации В коде вручную Механизм определения языка Принцип ближайшего соответствия Использование i18n в модулях Рекомендуемый способ: объявление ключей перевода через I18nClass (v2.7.0+) Ручная регистрация пользовательских переводов (старый способ) Использование перевода Использование в классе модуля Отмена регистрации перевода Многоязычные поля конфигурации Поддерживаемые i18n-поля Объявление i18n-полей Скрытие секретных данных и проверка конфигурации Регистрация перевода конфигурации Как WebUI потребляет Справочник API I18nManager BaseI18n / I18nKey (декларативные ключи перевода) Доступ через экземпляр SDK Конфигурация во время выполнения Чтение i18n-конфигурации через API конфигурации Описание конфигурационных параметров Лучшие практики Именование ключей перевода Многоязычное покрытие Динамический контент Журналы сообщений Отношение к i18n в CLI Связанные документы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Система международной локализации (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()

Механизм определения языка

Фреймворк определяет язык пользователя по следующему приоритету:

  1. Переменная окружения ERISPULSE_LANG — наивысший приоритет, используется для тестирования и временного переключения
  2. Windows API — GetUserDefaultLocaleName (только Windows, не подвергается влиянию таких инструментов, как Git Bash, которые могут переопределить LANG)
  3. Переменные окружения — LANGUAGE > LC_ALL > LC_MESSAGES > LANG (стандарт Unix/macOS)
  4. Системная локаль — locale.getlocale() / locale.getdefaultlocale()
  5. Обратный путь — 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 не повлияют на стабильность ядра фреймворка.

Связанные документы