1# aiogram_i18n Managers
2 
3This reference is based on the published `aiogram_i18n` source code.
4 
5Primary sources:
6- README and runtime example: https://github.com/aiogram/i18n
7- `middleware.py`: `I18nMiddleware(core=..., manager=..., default_locale=...)`
8- `managers/base.py`
9- `managers/const.py`
10- `managers/memory.py`
11- `managers/fsm.py`
12- `managers/redis.py`
13 
14## Core idea
15 
16`aiogram_i18n` uses a manager abstraction for locale storage and resolution.
17 
18The middleware:
19- keeps a `core`
20- keeps a `manager`
21- calls `manager.locale_getter(...)` on each update
22- exposes `manager.locale_setter(...)` through the runtime context
23 
24In source, `I18nMiddleware` defaults to `MemoryManager()` when no manager is provided.
25 
26## BaseManager
27 
28`BaseManager` defines the locale storage contract:
29- `get_locale(...) -> str`
30- `set_locale(...) -> None`
31- optional `startup(...)`
32- optional `shutdown(...)`
33 
34It also exposes callable wrappers:
35- `locale_getter`
36- `locale_setter`
37 
38That means runtime code can work against one manager interface while storage stays replaceable.
39 
40## Built-in managers
41 
42### ConstManager
43 
44Use when locale is fixed for the whole runtime.
45 
46Behavior from source:
47- `get_locale()` returns `default_locale`
48- `set_locale(...)` raises runtime error because this manager is immutable
49 
50### MemoryManager
51 
52Use when you want an in-process locale store keyed by aiogram FSM state key.
53 
54Behavior from source:
55- stores locale in an in-memory dict
56- reads and writes locale by `FSMContext.key`
57- simple, but process-local and non-persistent
58 
59### FSMManager
60 
61Use when locale should live in FSM data.
62 
63Behavior from source:
64- reads locale from FSM data by a configurable key, default `locale`
65- writes locale through `state.update_data(...)`
66- validates at startup that dispatcher is configured with FSM middleware
67 
68### RedisManager
69 
70Use when locale should persist in Redis.
71 
72Behavior from source:
73- uses aiogram Redis FSM primitives and key builder
74- stores locale under a Redis key derived from `state.key`
75- accepts either `Redis` or `ConnectionPool`
76 
77## Practical selection guide
78 
79- use `ConstManager` for single-locale bots or test setups
80- use `MemoryManager` for simple local state without persistence
81- use `FSMManager` when locale belongs to conversational state
82- use `RedisManager` when locale must survive restarts and scale across workers
83 
84## Important limitation
85 
86In the sources reviewed, `aiogram_i18n` documents runtime middleware and locale managers.
87 
88It 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.
89