Skip to content

I18n — Продвинутая локализация

Система локализации в codex-bot построена на базе Project Fluent и предоставляет инструменты для удобного управления переводами в сложных многомодульных проектах.

💎 Ключевые преимущества

1. Децентрализованное хранение

В отличие от классических систем, где все переводы лежат в одном огромном файле, codex-bot позволяет разбивать их на множество мелких .ftl файлов. Вы можете держать переводы прямо внутри папок с фичами, что упрощает поддержку кода.

2. Изоляция локалей (Path Hashing)

При запуске бота движок выполняет автоматическую компиляцию всех найденных файлов в одну временную директорию. - Механика: Путь к временной папке формируется как MD5(абсолютный_путь_к_проекту). - Зачем это нужно: Это гарантирует, что если на одном сервере запущено несколько разных ботов, они не будут конфликтовать и перезаписывать переводы друг друга в системной /tmp папке.

3. Автоматическая компиляция

Вам не нужно вручную запускать скрипты сборки. Метод compile_locales() вызывается автоматически при инициализации бота, собирая все разрозненные .ftl файлы в единые словари для каждого языка.

✍️ Как использовать

Определение переводов

Создайте файл greeting.ftl в папке вашей фичи:

# greeting.ftl
hello-user = Привет, {$name}! Добро пожаловать.

Использование в коде

Благодаря I18nMiddleware, объект для работы с переводами доступен глобально или через контекст:

# В оркестраторе или хендлере
from aiogram_i18n import I18nContext

async def render_content(self, payload, director: Director):
    i18n: I18nContext = director.container.i18n # или через контекст запроса
    text = i18n.get("hello-user", name="Alice")

    return ViewResultDTO(text=text)

⚙️ Настройка в проекте

В файле core/factory.py происходит связка компилятора и мидлвари:

from codex_bot.engine.i18n import compile_locales

# 1. Собираем все локали в изолированную папку
locales_path = compile_locales(pathlib.Path("resources/locales"))

# 2. Подключаем к aiogram
i18n_middleware = I18nMiddleware(
    core=FluentRuntimeCore(path=locales_path),
    manager=FSMContextI18nManager(),
)

🧭 Связанные разделы

  • Middlewares — подключение i18n в конвейер обработки.
  • API: Locales Compiler — технические детали процесса сборки.