Localization

Localization

Structure

app/localization/
├── translator.py       → t(), get_user_language(), menu action detection
├── translations.py     → compatibility facade (re-exports translator)
└── locales/
    ├── en.py           → English — single source of truth for all keys
    ├── uk.py           → Ukrainian
    ├── no.py           → Norwegian
    ├── de.py           → German
    ├── es.py           → Spanish
    ├── fr.py           → French
    ├── it.py           → Italian
    └── pl.py           → Polish

t() — Translation Function

from app.localization.translator import t

text = t("search_prompt", lang="uk")

t(key, lang) looks up key in the locale for lang. Falls back to English if the key is missing in the target locale. lang is a 2-letter code stored per user in PostgreSQL.

t() is a god node in the knowledge graph — 72 edges, cross-community bridge between bot layer, admin tools, keyboards, tests, and all service-facing text.

Adding a New Key

1. Add the key + English string to app/localization/locales/en.py
2. Add translations to all 7 other locale files
3. Run python scripts/check_locale_coverage.py — reports missing keys per locale

en.py is the single source of truth. Non-English locales are allowed to be incomplete — missing keys fall back to English at runtime.

Locale Coverage Checker

File: scripts/check_locale_coverage.py

CI gate. Reports:

uk: 48/48 keys (100%)
de: 47/48 keys (97.9%) — missing: search_no_results_extended

Run locally: python scripts/check_locale_coverage.py

Language Selection

Users select language via /language command or main menu. Selection saved to users.language column via set_user_language(pool, user_id, lang). Every subsequent t() call uses that stored value.

Default language for new users: English (en).