Welcome to aiogram-i18n’s documentation!¶

https://img.shields.io/pypi/v/aiogram-i18n.svg

https://img.shields.io/pypi/pyversions/aiogram-i18n.svg

https://img.shields.io/pypi/l/aiogram-i18n.svg

https://img.shields.io/pypi/dm/aiogram-i18n.svg

aiogram_i18n, an unrivalled middleware for Telegram bot internationalization, breathes life into bots, enabling diverse interactions in multiple languages, while adeptly managing user context, paving the way for a truly engaging and immersive user experience irrespective of language preference, and providing robust support for both Fluent and GNU gettext localization systems, thereby offering flexibility in translation file format selection, streamlining the translation process, and making the creation of multilingual bots an achievable goal for developers.

Installation¶

To install aiogram-i18n without any backends:

pip install aiogram-i18n

If you need help with what backend to choose, read Backends.

To use FluentCompileCore¶

To use fluent-compiler backend (aiogram_i18n.cores.fluent_compile_core.FluentCompileCore) install it:

pip install aiogram-i18n[compiler]

To use FluentRuntimeCore¶

To use Fluent.runtime backend (aiogram_i18n.cores.fluent_runtime_core.FluentRuntimeCore) install it:

pip install aiogram-i18n[runtime]

To use GNU gettext¶

To use gettext backend (aiogram_i18n.cores.gnu_text_core.py.GettextCore) install it:

pip install aiogram-i18n[gettext]

Usage example¶

import asyncio
from contextlib import suppress
from logging import INFO, basicConfig
from typing import Any

from aiogram import Bot, Dispatcher, Router
from aiogram.client.default import DefaultBotProperties
from aiogram.enums import ParseMode
from aiogram.filters import CommandStart
from aiogram.types import Message

from aiogram_i18n import I18nContext, I18nMiddleware, LazyProxy
from aiogram_i18n.cores.fluent_runtime_core import FluentRuntimeCore
from aiogram_i18n.lazy.filter import LazyFilter
from aiogram_i18n.types import (
    KeyboardButton,
    ReplyKeyboardMarkup,
)  # you should import mutable objects from here if you want to use LazyProxy in them

router = Router(name=__name__)
rkb = ReplyKeyboardMarkup(
    keyboard=[[KeyboardButton(text=LazyProxy("help"))]], resize_keyboard=True  # or L.help()
)


@router.message(CommandStart())
async def cmd_start(message: Message, i18n: I18nContext) -> Any:
    name = message.from_user.mention_html()
    return message.reply(
        text=i18n.get("hello", user=name), reply_markup=rkb  # or i18n.hello(user=name)
    )


@router.message(LazyFilter("help"))
async def cmd_help(message: Message) -> Any:
    return message.reply(text="-- " + message.text + " --")


async def main() -> None:
    basicConfig(level=INFO)
    bot = Bot("42:ABC", default=DefaultBotProperties(parse_mode=ParseMode.HTML))
    i18n_middleware = I18nMiddleware(core=FluentRuntimeCore(path="locales/{locale}/LC_MESSAGES"))

    dp = Dispatcher()
    dp.include_router(router)
    i18n_middleware.setup(dispatcher=dp)

    await dp.start_polling(bot)


if __name__ == "__main__":
    with suppress(KeyboardInterrupt):
        asyncio.run(main())

Indices and tables¶

Contents: