Add internationalization support and enhance language handling

- Introduced a new i18n module for managing translations and language normalization, supporting both Russian and English.
- Updated various handlers and services to utilize the new translation functions for user-facing messages, improving user experience based on language preferences.
- Enhanced error handling and response messages to be language-aware, ensuring appropriate feedback is provided to users in their preferred language.
- Added tests for the i18n module to validate language detection and translation functionality.
- Updated the example environment file to include a default language configuration.

duty_teller/i18n/__init__.py

@@ -0,0 +1,6 @@
+"""Internationalization: RU/EN by Telegram language_code. Normalize to 'ru' or 'en'."""
+
+from duty_teller.i18n.messages import MESSAGES
+from duty_teller.i18n.core import get_lang, t
+
+__all__ = ["MESSAGES", "get_lang", "t"]

duty_teller/i18n/core.py

@@ -0,0 +1,37 @@
+"""get_lang and t(): language from Telegram user, translate by key with fallback to en."""
+
+from typing import TYPE_CHECKING
+
+import duty_teller.config as config
+from duty_teller.i18n.messages import MESSAGES
+
+if TYPE_CHECKING:
+    from telegram import User
+
+
+def get_lang(user: "User | None") -> str:
+    """
+    Normalize Telegram user language to 'ru' or 'en'.
+    If user has language_code starting with 'ru' (e.g. ru, ru-RU) return 'ru', else 'en'.
+    When user is None or has no language_code, return config.DEFAULT_LANGUAGE.
+    """
+    if user is None or not getattr(user, "language_code", None):
+        return config.DEFAULT_LANGUAGE
+    code = (user.language_code or "").strip().lower()
+    return "ru" if code.startswith("ru") else "en"
+
+
+def t(lang: str, key: str, **kwargs: str) -> str:
+    """
+    Return translated string for lang and key; substitute kwargs into placeholders like {phone}.
+    Fallback to 'en' if key missing for lang.
+    """
+    lang = "ru" if lang == "ru" else "en"
+    messages = MESSAGES.get(lang) or MESSAGES["en"]
+    template = messages.get(key)
+    if template is None:
+        template = MESSAGES["en"].get(key, key)
+    try:
+        return template.format(**kwargs)
+    except KeyError:
+        return template

duty_teller/i18n/messages.py

@@ -0,0 +1,82 @@
+"""Translation dictionaries: MESSAGES[lang][key]. Keys: dotted, e.g. start.greeting."""
+
+MESSAGES: dict[str, dict[str, str]] = {
+    "en": {
+        "start.greeting": "Hi! I'm the duty calendar bot. Use /help for the command list.",
+        "set_phone.private_only": "The /set_phone command is only available in private chat.",
+        "set_phone.saved": "Phone saved: {phone}",
+        "set_phone.cleared": "Phone cleared.",
+        "set_phone.error": "Error saving.",
+        "help.title": "Available commands:",
+        "help.start": "/start — Start",
+        "help.help": "/help — Show this help",
+        "help.set_phone": "/set_phone — Set or clear phone for duty display",
+        "help.pin_duty": "/pin_duty — In a group: pin the duty message (bot needs admin with Pin messages)",
+        "help.import_schedule": "/import_duty_schedule — Import duty schedule (JSON)",
+        "errors.generic": "An error occurred. Please try again later.",
+        "pin_duty.group_only": "The /pin_duty command works only in groups.",
+        "pin_duty.no_message": "There is no duty message in this chat yet. Add the bot to the group — it will create one automatically.",
+        "pin_duty.pinned": "Duty message pinned.",
+        "pin_duty.failed": "Could not pin. Make sure the bot is an administrator with «Pin messages» permission.",
+        "pin_duty.could_not_pin_make_admin": "Duty message was sent but could not be pinned. Make the bot an administrator with «Pin messages» permission, then send /pin_duty in the chat — the current message will be pinned.",
+        "duty.no_duty": "No duty at the moment.",
+        "duty.label": "Duty:",
+        "import.admin_only": "Access for administrators only.",
+        "import.handover_format": "Enter handover time as HH:MM and timezone, e.g. 09:00 Europe/Moscow or 06:00 UTC.",
+        "import.parse_time_error": "Could not parse time. Enter e.g.: 09:00 Europe/Moscow",
+        "import.send_json": "Send the duty-schedule file (JSON).",
+        "import.need_json": "File must have .json extension.",
+        "import.parse_error": "File parse error: {error}",
+        "import.import_error": "Import error: {error}",
+        "import.done": "Import done: {users} users, {duties} duties{unavailable}{vacation} ({total} events total).",
+        "import.done_unavailable": ", {count} unavailable",
+        "import.done_vacation": ", {count} vacation",
+        "api.open_from_telegram": "Open the calendar from Telegram",
+        "api.auth_bad_signature": "Invalid signature. Ensure BOT_TOKEN on the server matches the bot from which the calendar was opened (same bot as in the menu).",
+        "api.auth_invalid": "Invalid auth data",
+        "api.access_denied": "Access denied",
+        "dates.bad_format": "Parameters from and to must be in YYYY-MM-DD format",
+        "dates.from_after_to": "from date must not be after to",
+    },
+    "ru": {
+        "start.greeting": "Привет! Я бот календаря дежурств. Используй /help для списка команд.",
+        "set_phone.private_only": "Команда /set_phone доступна только в личке.",
+        "set_phone.saved": "Телефон сохранён: {phone}",
+        "set_phone.cleared": "Телефон очищен.",
+        "set_phone.error": "Ошибка сохранения.",
+        "help.title": "Доступные команды:",
+        "help.start": "/start — Начать",
+        "help.help": "/help — Показать эту справку",
+        "help.set_phone": "/set_phone — Указать или очистить телефон для отображения в дежурстве",
+        "help.pin_duty": "/pin_duty — В группе: закрепить сообщение о дежурстве (нужны права админа у бота)",
+        "help.import_schedule": "/import_duty_schedule — Импорт расписания дежурств (JSON)",
+        "errors.generic": "Произошла ошибка. Попробуйте позже.",
+        "pin_duty.group_only": "Команда /pin_duty работает только в группах.",
+        "pin_duty.no_message": "В этом чате ещё нет сообщения о дежурстве. Добавьте бота в группу — оно создастся автоматически.",
+        "pin_duty.pinned": "Сообщение о дежурстве закреплено.",
+        "pin_duty.failed": "Не удалось закрепить. Убедитесь, что бот — администратор с правом «Закреплять сообщения».",
+        "pin_duty.could_not_pin_make_admin": "Сообщение о дежурстве отправлено, но закрепить его не удалось. "
+        "Сделайте бота администратором с правом «Закреплять сообщения» (Pin messages), "
+        "затем отправьте в чат команду /pin_duty — текущее сообщение будет закреплено.",
+        "duty.no_duty": "Сейчас дежурства нет.",
+        "duty.label": "Дежурство:",
+        "import.admin_only": "Доступ только для администраторов.",
+        "import.handover_format": "Укажите время пересменки в формате ЧЧ:ММ и часовой пояс, "
+        "например 09:00 Europe/Moscow или 06:00 UTC.",
+        "import.parse_time_error": "Не удалось разобрать время. Укажите, например: 09:00 Europe/Moscow",
+        "import.send_json": "Отправьте файл в формате duty-schedule (JSON).",
+        "import.need_json": "Нужен файл с расширением .json",
+        "import.parse_error": "Ошибка разбора файла: {error}",
+        "import.import_error": "Ошибка импорта: {error}",
+        "import.done": "Импорт выполнен: {users} пользователей, {duties} дежурств{unavailable}{vacation} (всего {total} событий).",
+        "import.done_unavailable": ", {count} недоступностей",
+        "import.done_vacation": ", {count} отпусков",
+        "api.open_from_telegram": "Откройте календарь из Telegram",
+        "api.auth_bad_signature": "Неверная подпись. Убедитесь, что BOT_TOKEN на сервере совпадает с токеном бота, "
+        "из которого открыт календарь (тот же бот, что в меню).",
+        "api.auth_invalid": "Неверные данные авторизации",
+        "api.access_denied": "Доступ запрещён",
+        "dates.bad_format": "Параметры from и to должны быть в формате YYYY-MM-DD",
+        "dates.from_after_to": "Дата from не должна быть позже to",
+    },
+}