Dev 3.x i18n & improvements (#696)

* Added base code and make code improvements
* Auto-exclude coverage for `if TYPE_CHECKING:`
* Fixed current coverage
* Cover I18n module
* Update pipeline
* Fixed annotations
* Added docs
* Move exceptions
* Added tests for KeyboardBuilder and initial docs
* Remove help generator (removed from sources tree, requires rewrite)
* Added patch-notes #698, #699, #700, #701, #702, #703

docs/_static/stylesheets/extra.css

@@ -10,13 +10,3 @@
 code, kbd, pre {
     font-family: "JetBrainsMono", "Roboto Mono", "Courier New", Courier, monospace;
 }
-
-.highlight * {
-    background: #f0f0f0;
-}
-
-@media (prefers-color-scheme: dark) {
-    .highlight * {
-        background: #424242;
-    }
-}

docs/index.rst

@@ -93,4 +93,5 @@ Contents
     install
     api/index
     dispatcher/index
+    utils/index
     changelog

docs/utils/i18n.rst

@@ -0,0 +1,190 @@
+===========
+Translation
+===========
+
+In order to make you bot translatable you have to add a minimal number of hooks to your Python code.
+
+These hooks are called translation strings.
+
+The aiogram translation utils is build on top of `GNU gettext Python module <https://docs.python.org/3/library/gettext.html>`_
+and `Babel library <http://babel.pocoo.org/en/latest/>`_.
+
+Installation
+============
+
+Babel is required to make simple way to extract translation strings from your code
+
+Can be installed from pip directly:
+
+.. code-block:: bash
+
+    pip install Babel
+
+
+or as `aiogram` extra dependency:
+
+.. code-block:: bash
+
+    pip install aiogram[i18n]
+
+
+Make messages translatable
+==========================
+
+In order to gettext need to know what the strings should be translated you will need to write translation strings.
+
+For example:
+
+.. code-block:: python
+    :emphasize-lines: 6-8
+
+    from aiogram import html
+    from aiogram.utils.i18n import gettext as _
+
+    async def my_handler(message: Message) -> None:
+        await message.answer(
+            _("Hello, {name}!").format(
+                name=html.quote(message.from_user.full_name)
+            )
+        )
+
+
+.. danger::
+
+    f-strings can't be used as translations string because any dynamic variables should be added to message after getting translated message
+
+
+Also if you want to use translated string in keyword- or magic- filters you will need to use lazy gettext calls:
+
+
+.. code-block:: python
+    :emphasize-lines: 4
+
+    from aiogram import F
+    from aiogram.utils.i18n import lazy_gettext as __
+
+    @router.message(F.text.lower() == __("My menu entry"))
+    ...
+
+
+.. danger::
+
+    Lazy gettext calls should always be used when the current language is not know at the moment
+
+
+.. danger::
+
+    Lazy gettext can't be used as value for API methods or any Telegram Object (like :class:`aiogram.types.inline_keyboard_button.InlineKeyboardButton` or etc.)
+
+Configuring engine
+==================
+
+After you messages is already done to use gettext your bot should know how to detect user language
+
+On top of your application the instance of :class:`aiogram.utils.i18n.code.I18n` should be created
+
+
+.. code-block::
+
+    i18n = I18n(path="locales", language="en", domain="messages")
+
+
+After that you will need to choose one of builtin I18n middleware or write your own.
+
+Builtin middlewares:
+
+
+SimpleI18nMiddleware
+~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: aiogram.utils.i18n.middleware.SimpleI18nMiddleware
+    :members: __init__
+
+ConstI18nMiddleware
+~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: aiogram.utils.i18n.middleware.ConstI18nMiddleware
+    :members: __init__
+
+FSMI18nMiddleware
+~~~~~~~~~~~~~~~~~
+
+.. autoclass:: aiogram.utils.i18n.middleware.FSMI18nMiddleware
+    :members: __init__,set_locale
+
+
+I18nMiddleware
+~~~~~~~~~~~~~~
+
+or define you own based on abstract I18nMiddleware middleware:
+
+.. autoclass:: aiogram.utils.i18n.middleware.FSMI18nMiddleware
+    :members: __init__,setup,get_locale
+
+
+Deal with Babel
+===============
+
+Step 1: Extract messages
+-------------------
+
+.. code-block:: bash
+
+    pybabel extract --input-dirs=. -o locales/messages.pot
+
+
+Here is :code:`--input-dirs=.` - path to code and the :code:`locales/messages.pot`
+is template where messages will be extracted and `messages` is translation domain.
+
+.. note::
+
+    Some useful options:
+
+    - Extract texts with pluralization support :code:`-k __:1,2`
+    - Add comments for translators, you can use another tag if you want (TR) :code:`--add-comments=NOTE`
+    - Disable comments with string location in code :code:`--no-location`
+    - Set project name :code:`--project=MySuperBot`
+    - Set version :code:`--version=2.2`
+
+
+Step 2: Init language
+----------------
+
+.. code-block:: bash
+
+    pybabel init -i locales/messages.pot -d locales -D messages -l en
+
+- :code:`-i locales/messages.pot` - pre-generated template
+- :code:`-d locales` - translations directory
+- :code:`-D messages` - translations domain
+- :code:`-l en` - language. Can be changed to any other valid language code (For example :code:`-l uk` for ukrainian language)
+
+
+Step 3: Translate texts
+-----------------------
+
+To open .po file you can use basic text editor or any PO editor, e.g. `Poedit <https://poedit.net/>`_
+
+Just open the file named :code:`locales/{language}/LC_MESSAGES/messages.po` and write translations
+
+Step 4: Compile translations
+----------------------------
+
+.. code-block:: bash
+
+    pybabel compile -d locales -D messages
+
+
+Step 5: Updating messages
+-------------------------
+
+When you change the code of your bot you need to update po & mo files
+
+- Step 5.1: regenerate pot file: command from step 1
+- Step 5.2: update po files
+    .. code-block::
+
+        pybabel update -d locales -D messages -i locales/messages.pot
+
+- Step 5.3: update your translations: location and tools you know from step 3
+- Step 5.4: compile mo files: command from step 4

docs/utils/index.rst

@@ -0,0 +1,8 @@
+=====
+Utils
+=====
+
+.. toctree::
+
+    i18n
+    keyboard

docs/utils/keyboard.rst

@@ -0,0 +1,24 @@
+================
+Keyboard builder
+================
+
+Inline Keyboard
+===============
+
+.. autoclass:: aiogram.utils.keyboard.InlineKeyboardBuilder
+    :members: __init__, buttons, copy, export, add, row, adjust, button, as_markup
+    :undoc-members: True
+
+Reply Keyboard
+==============
+
+.. autoclass:: aiogram.utils.keyboard.ReplyKeyboardBuilder
+    :members: __init__, buttons, copy, export, add, row, adjust, button, as_markup
+    :undoc-members: True
+
+
+Base builder
+============
+.. autoclass:: aiogram.utils.keyboard.ReplyKeyboardBuilder
+    :members: __init__, buttons, copy, export, add, row, adjust, button, as_markup
+    :undoc-members: True