aiogram_i18n Managers

This reference is based on the published aiogram_i18n source code.

Primary sources:

• README and runtime example: https://github.com/aiogram/i18n
• middleware.py: I18nMiddleware(core=..., manager=..., default_locale=...)
• managers/base.py
• managers/const.py
• managers/memory.py
• managers/fsm.py
• managers/redis.py

Core idea

aiogram_i18n uses a manager abstraction for locale storage and resolution.

The middleware:

• keeps a core
• keeps a manager
• calls manager.locale_getter(...) on each update
• exposes manager.locale_setter(...) through the runtime context

In source, I18nMiddleware defaults to MemoryManager() when no manager is provided.

BaseManager

BaseManager defines the locale storage contract:

• get_locale(...) -> str
• set_locale(...) -> None
• optional startup(...)
• optional shutdown(...)

It also exposes callable wrappers:

• locale_getter
• locale_setter

That means runtime code can work against one manager interface while storage stays replaceable.

Built-in managers

ConstManager

Use when locale is fixed for the whole runtime.

Behavior from source:

• get_locale() returns default_locale
• set_locale(...) raises runtime error because this manager is immutable

MemoryManager

Use when you want an in-process locale store keyed by aiogram FSM state key.

Behavior from source:

• stores locale in an in-memory dict
• reads and writes locale by FSMContext.key
• simple, but process-local and non-persistent

FSMManager

Use when locale should live in FSM data.

Behavior from source:

• reads locale from FSM data by a configurable key, default locale
• writes locale through state.update_data(...)
• validates at startup that dispatcher is configured with FSM middleware

RedisManager

Use when locale should persist in Redis.

Behavior from source:

• uses aiogram Redis FSM primitives and key builder
• stores locale under a Redis key derived from state.key
• accepts either Redis or ConnectionPool

Practical selection guide

• use ConstManager for single-locale bots or test setups
• use MemoryManager for simple local state without persistence
• use FSMManager when locale belongs to conversational state
• use RedisManager when locale must survive restarts and scale across workers

Important limitation

In the sources reviewed, aiogram_i18n documents runtime middleware and locale managers.

It does not document a built-in translation extraction or code-generation CLI in the same way. Treat translation extraction, catalog generation, and locale scaffolding as a separate project toolchain concern unless your repository provides an explicit command for them.