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/api/dependencies.py

@@ -1,6 +1,7 @@
 """FastAPI dependencies: DB session, auth, date validation."""
 
 import logging
+import re
 from typing import Annotated, Generator
 
 from fastapi import Header, HTTPException, Query, Request
@@ -11,23 +12,55 @@ from duty_teller.api.telegram_auth import validate_init_data_with_reason
 from duty_teller.db.repository import get_duties
 from duty_teller.db.schemas import DutyWithUser
 from duty_teller.db.session import session_scope
+from duty_teller.i18n import t
 from duty_teller.utils.dates import validate_date_range
 
 log = logging.getLogger(__name__)
 
+# First language tag from Accept-Language (e.g. "ru-RU,ru;q=0.9,en;q=0.8" -> "ru")
+_ACCEPT_LANG_TAG_RE = re.compile(r"^([a-zA-Z]{2,3})(?:-[a-zA-Z0-9]+)?\s*(?:;|,|$)")
 
-def _validate_duty_dates(from_date: str, to_date: str) -> None:
+
+def _lang_from_accept_language(header: str | None) -> str:
+    """Normalize Accept-Language to 'ru' or 'en'; fallback to config.DEFAULT_LANGUAGE."""
+    if not header or not header.strip():
+        return config.DEFAULT_LANGUAGE
+    first = header.strip().split(",")[0].strip()
+    m = _ACCEPT_LANG_TAG_RE.match(first)
+    if not m:
+        return "en"
+    code = m.group(1).lower()
+    return "ru" if code.startswith("ru") else "en"
+
+
+def _auth_error_detail(auth_reason: str, lang: str) -> str:
+    """Return translated auth error message."""
+    if auth_reason == "hash_mismatch":
+        return t(lang, "api.auth_bad_signature")
+    return t(lang, "api.auth_invalid")
+
+
+def _validate_duty_dates(from_date: str, to_date: str, lang: str) -> None:
+    """Validate date range; raise HTTPException with translated detail."""
     try:
         validate_date_range(from_date, to_date)
     except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e)) from e
+        msg = str(e)
+        if "YYYY-MM-DD" in msg or "формате" in msg:
+            detail = t(lang, "dates.bad_format")
+        else:
+            detail = t(lang, "dates.from_after_to")
+        raise HTTPException(status_code=400, detail=detail) from e
 
 
 def get_validated_dates(
+    request: Request,
     from_date: str = Query(..., description="ISO date YYYY-MM-DD", alias="from"),
     to_date: str = Query(..., description="ISO date YYYY-MM-DD", alias="to"),
 ) -> tuple[str, str]:
-    _validate_duty_dates(from_date, to_date)
+    """Validate from/to dates; lang from Accept-Language for error messages."""
+    lang = _lang_from_accept_language(request.headers.get("Accept-Language"))
+    _validate_duty_dates(from_date, to_date, lang)
     return (from_date, to_date)
 
 
@@ -45,15 +78,6 @@ def require_miniapp_username(
     return get_authenticated_username(request, x_telegram_init_data)
 
 
-def _auth_error_detail(auth_reason: str) -> str:
-    if auth_reason == "hash_mismatch":
-        return (
-            "Неверная подпись. Убедитесь, что BOT_TOKEN на сервере совпадает с токеном бота, "
-            "из которого открыт календарь (тот же бот, что в меню)."
-        )
-    return "Неверные данные авторизации"
-
-
 def _is_private_client(client_host: str | None) -> bool:
     if not client_host:
         return False
@@ -81,17 +105,20 @@ def get_authenticated_username(
                 log.warning("allowing without initData (MINI_APP_SKIP_AUTH is set)")
             return ""
         log.warning("no X-Telegram-Init-Data header (client=%s)", client_host)
-        raise HTTPException(status_code=403, detail="Откройте календарь из Telegram")
+        lang = _lang_from_accept_language(request.headers.get("Accept-Language"))
+        raise HTTPException(status_code=403, detail=t(lang, "api.open_from_telegram"))
     max_age = config.INIT_DATA_MAX_AGE_SECONDS or None
-    username, auth_reason = validate_init_data_with_reason(
+    username, auth_reason, lang = validate_init_data_with_reason(
         init_data, config.BOT_TOKEN, max_age_seconds=max_age
     )
     if username is None:
         log.warning("initData validation failed: %s", auth_reason)
-        raise HTTPException(status_code=403, detail=_auth_error_detail(auth_reason))
+        raise HTTPException(
+            status_code=403, detail=_auth_error_detail(auth_reason, lang)
+        )
     if not config.can_access_miniapp(username):
         log.warning("username not in allowlist: %s", username)
-        raise HTTPException(status_code=403, detail="Доступ запрещён")
+        raise HTTPException(status_code=403, detail=t(lang, "api.access_denied"))
     return username
 
 

duty_teller/api/telegram_auth.py

@@ -16,21 +16,32 @@ def validate_init_data(
     max_age_seconds: int | None = None,
 ) -> str | None:
     """Validate initData and return username; see validate_init_data_with_reason for failure reason."""
-    username, _ = validate_init_data_with_reason(init_data, bot_token, max_age_seconds)
+    username, _, _ = validate_init_data_with_reason(
+        init_data, bot_token, max_age_seconds
+    )
     return username
 
 
+def _normalize_lang(language_code: str | None) -> str:
+    """Normalize to 'ru' or 'en' for i18n."""
+    if not language_code or not isinstance(language_code, str):
+        return "en"
+    code = language_code.strip().lower()
+    return "ru" if code.startswith("ru") else "en"
+
+
 def validate_init_data_with_reason(
     init_data: str,
     bot_token: str,
     max_age_seconds: int | None = None,
-) -> tuple[str | None, str]:
+) -> tuple[str | None, str, str]:
     """
-    Validate initData signature and return (username, None) or (None, reason).
+    Validate initData signature and return (username, reason, lang) or (None, reason, lang).
     reason is one of: "ok", "empty", "no_hash", "hash_mismatch", "auth_date_expired", "no_user", "user_invalid", "no_username".
+    lang is from user.language_code normalized to 'ru' or 'en'; 'en' when no user.
     """
     if not init_data or not bot_token:
-        return (None, "empty")
+        return (None, "empty", "en")
     init_data = init_data.strip()
     params = {}
     for part in init_data.split("&"):
@@ -42,7 +53,7 @@ def validate_init_data_with_reason(
         params[key] = value
     hash_val = params.pop("hash", None)
     if not hash_val:
-        return (None, "no_hash")
+        return (None, "no_hash", "en")
     data_pairs = sorted(params.items())
     # Data-check string: key=value with URL-decoded values (per Telegram example)
     data_string = "\n".join(f"{k}={unquote(v)}" for k, v in data_pairs)
@@ -58,27 +69,28 @@ def validate_init_data_with_reason(
         digestmod=hashlib.sha256,
     ).hexdigest()
     if not hmac.compare_digest(computed.lower(), hash_val.lower()):
-        return (None, "hash_mismatch")
+        return (None, "hash_mismatch", "en")
     if max_age_seconds is not None and max_age_seconds > 0:
         auth_date_raw = params.get("auth_date")
         if not auth_date_raw:
-            return (None, "auth_date_expired")
+            return (None, "auth_date_expired", "en")
         try:
             auth_date = int(float(auth_date_raw))
         except (ValueError, TypeError):
-            return (None, "auth_date_expired")
+            return (None, "auth_date_expired", "en")
         if time.time() - auth_date > max_age_seconds:
-            return (None, "auth_date_expired")
+            return (None, "auth_date_expired", "en")
     user_raw = params.get("user")
     if not user_raw:
-        return (None, "no_user")
+        return (None, "no_user", "en")
     try:
         user = json.loads(unquote(user_raw))
     except (json.JSONDecodeError, TypeError):
-        return (None, "user_invalid")
+        return (None, "user_invalid", "en")
     if not isinstance(user, dict):
-        return (None, "user_invalid")
+        return (None, "user_invalid", "en")
+    lang = _normalize_lang(user.get("language_code"))
     username = user.get("username")
     if not username or not isinstance(username, str):
-        return (None, "no_username")
-    return (username.strip().lstrip("@").lower(), "ok")
+        return (None, "no_username", lang)
+    return (username.strip().lstrip("@").lower(), "ok", lang)