Metadata-Version: 2.4
Name: aiogram-dialog-i18n
Version: 0.2.0
Summary: i18n text widget for aiogram-dialog powered by aiogram-i18n or fluentogram
Keywords: aiogram,aiogram-dialog,i18n,fluent,fluentogram,gettext,telegram
Author: m-xim
Author-email: m-xim <i@m-xim.ru>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Dist: aiogram-dialog>=2.0.0
Requires-Dist: magic-filter>=1.0.12
Requires-Dist: aiogram-i18n>=1.5 ; extra == 'aiogram-i18n'
Requires-Dist: fluentogram>=1.1.10 ; extra == 'fluentogram'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/m-xim/aiogram-dialog-i18n
Project-URL: Repository, https://github.com/m-xim/aiogram-dialog-i18n
Project-URL: Issues, https://github.com/m-xim/aiogram-dialog-i18n/issues
Provides-Extra: aiogram-i18n
Provides-Extra: fluentogram
Description-Content-Type: text/markdown

# aiogram-dialog-i18n

[![PyPI version](https://img.shields.io/pypi/v/aiogram-dialog-i18n?color=blue)](https://pypi.org/project/aiogram-dialog-i18n)
[![codecov](https://codecov.io/github/m-xim/aiogram-dialog-i18n/graph/badge.svg)](https://codecov.io/github/m-xim/aiogram-dialog-i18n)
[![Tests Status](https://github.com/m-xim/aiogram-dialog-i18n/actions/workflows/tests.yml/badge.svg)](https://github.com/m-xim/aiogram-dialog-i18n/actions)
[![License](https://img.shields.io/github/license/m-xim/aiogram-dialog-i18n.svg)](/LICENSE)
[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)

Translated text widget for [aiogram-dialog](https://github.com/Tishka17/aiogram_dialog) powered by [aiogram-i18n](https://github.com/aiogram/i18n) or [fluentogram](https://github.com/Arustinal/fluentogram).

The examples use these translations:

```ftl
hello-user = Hello, { $name }! Balance: { $balance }
payment-method = • { $method }
pay-btn = Pay
```

## aiogram-i18n

### Installation

```bash
uv add "aiogram-dialog-i18n[aiogram-i18n]"
# or
pip install "aiogram-dialog-i18n[aiogram-i18n]"
```

### Setup

Set up `I18nMiddleware` as usual.

### Usage

`I18nFormat`, short alias `T`:

```python
from aiogram_dialog import Window
from aiogram_dialog.widgets.kbd import Button
from aiogram_dialog.widgets.text import Format, List
from magic_filter import F

from aiogram_dialog_i18n.aiogram_i18n import I18nFormat, T

Window(
    I18nFormat("hello-user", name=F["user"].full_name, balance=Format("{balance:.2f}")),
    List(T("payment-method", method=F["item"]), F["methods"]),
    Button(T("pay-btn"), id="pay", when=F["methods"]),
    state=...,
)
```

## fluentogram

### Installation

```bash
uv add "aiogram-dialog-i18n[fluentogram]"
# or
pip install "aiogram-dialog-i18n[fluentogram]"
```

### Setup

`FluentogramMiddleware` puts the `TranslatorRunner` of the user and the `TranslatorHub` into the data, set it up after the other middlewares:

```python
from aiogram_dialog_i18n.fluentogram import FluentogramMiddleware

FluentogramMiddleware(hub).setup(dp)
```

To take the locale from a database, override `get_locale`:

```python
class DbFluentogramMiddleware(FluentogramMiddleware):
    async def get_locale(self, event, data):
        user = await data["repo"].get_user(data["event_from_user"].id)
        return user.language if user else None


DbFluentogramMiddleware(hub).setup(dp)
```

### Usage

`FluentogramFormat`, short alias `T`:

```python
from aiogram_dialog import Window
from aiogram_dialog.widgets.kbd import Button
from aiogram_dialog.widgets.text import Format, List
from magic_filter import F

from aiogram_dialog_i18n.fluentogram import FluentogramFormat, T

Window(
    FluentogramFormat("hello-user", name=F["user"].full_name, balance=Format("{balance:.2f}")),
    List(T("payment-method", method=F["item"]), F["methods"]),
    Button(T("pay-btn"), id="pay", when=F["methods"]),
    state=...,
)
```

Outside widgets, take them from the data: `i18n` is the `TranslatorRunner` of the user, `translator_hub` is the `TranslatorHub`:

```python
from aiogram.filters import Command
from aiogram.types import Message
from fluentogram import TranslatorHub, TranslatorRunner


@router.message(Command("start"))
async def start(message: Message, i18n: TranslatorRunner, translator_hub: TranslatorHub):
    await message.answer(i18n.get("hello-user", name=message.from_user.full_name))
    # another locale
    await message.answer(translator_hub.get_translator_by_locale("en").get("pay-btn"))
```

In aiogram-dialog callbacks and getters they are in `dialog_manager.middleware_data["i18n"]` and `dialog_manager.middleware_data["translator_hub"]`.

## Arguments

```python
I18nFormat(key, locale=None, /, *, when=None, **params)
FluentogramFormat(key, locale=None, /, *, when=None, **params)
```

- `key`: the translation key.
- `locale`: overrides the user's locale; positional-only, so `locale=...` is still a message param.
- `when`: the usual aiogram-dialog condition, not a message param.
- `params`: a text widget (rendered), a `MagicFilter` (resolved against window data) or a constant. `None` becomes `""`, so in Jinja2 use `{% if x %}`, not `is none`.

`locale` can be a constant, a magic filter or a text widget:

```python
T("k", "en")  # fixed locale
T("k", F["lang"])  # locale from window data
T("k", locale=F["lang"])  # not a locale: a message param named "locale"
```

## Preview

There is no middleware data in `aiogram_dialog.tools.render_preview`, so both widgets show the key with its params instead of a translation. An empty value is shown as `{name}`, like `Format` does. The window from the examples looks like this:

<img src="https://raw.githubusercontent.com/m-xim/aiogram-dialog-i18n/main/assets/preview-keys.png" width="360" alt="Preview of the window: the key with its params">

With the middleware the same window is rendered with translations, here in English and Russian:

| English | Русский |
|---|---|
| <img src="https://raw.githubusercontent.com/m-xim/aiogram-dialog-i18n/main/assets/preview-en.png" width="360" alt="Window in English"> | <img src="https://raw.githubusercontent.com/m-xim/aiogram-dialog-i18n/main/assets/preview-ru.png" width="360" alt="Window in Russian"> |
