1# aiogram_i18n with Fluent/FTL
2 
3This reference covers runtime usage of `aiogram_i18n` for aiogram 3.
4 
5Primary sources:
6- Context7 aiogram_i18n library: `/aiogram/i18n`
7- Context7 aiogram 3 library: `/aiogram/aiogram/v3.25.0`
8- GitHub: https://github.com/aiogram/i18n
9- PyPI: https://pypi.org/project/aiogram_i18n/
10 
11Use Context7 first for exact examples and current API shape, then fall back to GitHub or PyPI when you need package prose or details that are not covered in snippets.
12 
13## Installation
14 
15Base package:
16```bash
17pip install aiogram_i18n
18```
19 
20For Fluent Runtime:
21```bash
22pip install fluent.runtime
23```
24 
25For Fluent Compile Core:
26```bash
27pip install fluent_compiler
28```
29 
30## Core setup
31 
32The documented basic runtime setup uses `I18nMiddleware` with `FluentRuntimeCore`.
33 
34Minimal shape:
35```python
36from aiogram import Bot, Dispatcher, Router
37from aiogram_i18n import I18nContext, I18nMiddleware
38from aiogram_i18n.cores.fluent_runtime_core import FluentRuntimeCore
39 
40router = Router()
41 
42i18n_middleware = I18nMiddleware(
43    core=FluentRuntimeCore(
44        path="locales/{locale}/LC_MESSAGES"
45    )
46)
47 
48dp = Dispatcher()
49dp.include_router(router)
50i18n_middleware.setup(dispatcher=dp)
51```
52 
53This registration pattern is shown in the project README/PyPI description.
54 
55## Locale file layout
56 
57For Fluent Runtime, the documented path shape is:
58```text
59locales/
60  en/
61    LC_MESSAGES/
62      messages.ftl
63  uk/
64    LC_MESSAGES/
65      messages.ftl
66```
67 
68The exact FTL file name is project-defined, but the locale directory structure should match the configured path template.
69 
70## Handler usage
71 
72Handlers can receive `I18nContext` directly and render strings through:
73- `i18n.get("key", arg=value)`
74- `i18n.key(arg=value)`
75 
76Example:
77```python
78@router.message(...)
79async def handler(message: Message, i18n: I18nContext) -> None:
80    await message.answer(i18n.get("hello", user=message.from_user.full_name))
81```
82 
83## Lazy translations
84 
85The documented package also exposes:
86- `LazyProxy`
87- `LazyFilter`
88 
89Useful cases:
90- localized keyboard button labels
91- matching localized button text in filters
92 
93Important package note from the docs:
94- if you use `LazyProxy` inside mutable Telegram objects, import those mutable objects from `aiogram_i18n.types`
95 
96## Locale persistence pattern
97 
98`aiogram_i18n` is the runtime i18n layer. Your project still needs to decide how locale is stored.
99 
100A universal pattern is:
1011. resolve target locale from callback data, command args, profile, or Telegram user language
1022. persist locale in your own storage layer
1033. call `await i18n.set_locale(...)`
1044. re-render the current screen in the new locale
105 
106Use `scripts/i18n_callback_query.py` for the handler shape.
107 
108## Extraction and generation workflow
109 
110`aiogram_i18n` itself is the runtime layer. Extraction and locale-file generation usually come from a separate tool.
111 
112One concrete FTL-oriented tool is `FTL-Extract`:
113- PyPI: https://pypi.org/project/FTL-Extract/
114- command: `ftl_extract`
115 
116Example usage from the published tool docs:
117```bash
118pip install FTL-Extract
119ftl_extract project_path/code_path project_path/locales
120```
121 
122The same tool also documents multi-locale extraction, for example:
123```bash
124ftl_extract project_path/code_path project_path/locales -l en -l uk -l pl
125```
126 
127And custom i18n key discovery, for example:
128```bash
129ftl_extract project_path/code_path project_path/locales -k i18n -k LazyProxy -k L
130```
131 
132Important boundary:
133- this command comes from `FTL-Extract`, not from `aiogram_i18n`
134- if a repository uses another extractor or a wrapper command, document that repository-specific command separately
135- do not present a project wrapper as universal unless it is actually part of the chosen toolchain
136 
137## Minimal FTL example
138 
139```ftl
140hello = Hello, { $user }!
141language-select-prompt = Choose your language.
142language-changed-success = Language updated.
143```
144 
145## Practical rules
146 
147- keep keys stable and semantic
148- re-render UI after locale changes
149- avoid hard-coded English strings in callbacks
150- treat locale storage and locale rendering as separate concerns
151