bober-bbq-bot/docs/I18N.md

Internationalization (i18n)

This document describes the i18n scaffolding added to the customer-facing surfaces of the app: the Telegram bot (bot/), the Flask-side customer notifications (bober_bbq/utils/notify_customer.py, bober_bbq/utils/telegram_notify.py), and the React/Vite Mini App (webapp/).

The admin panel (bober_bbq/templates/admin/*, bober_bbq/admin/*.py) is explicitly out of scope and stays hardcoded in Ukrainian — it's an internal tool used only by Ukrainian-speaking cafe staff.

This started as scaffolding proven on one slice (cart/checkout) and has since been extended to cover every customer-facing screen and message: the whole Mini App (menu, cart, checkout, orders, contacts, closed/announcement banners, navigation), every reachable bot message, and — via Category.name_en / Product.name_en / Product.description_en — the menu content itself. See "What's translated today" below for the precise boundary and the handful of things still deliberately left in Ukrainian.

Why not a framework?

The codebase has no existing i18n dependency, and the rest of it favors small, dependency-free patterns already (e.g. Setting.get(key, default) in bober_bbq/models.py). Pulling in Flask-Babel for the backend or react-i18next for the Mini App would mean a new config surface, message-catalog build step, and a heavier mental model for a project this size. Instead:

• Backend: a plain Python dict of dicts (TRANSLATIONS) plus a t(key, locale, **kwargs) lookup function, in the same spirit as Setting.get.
• Webapp: a plain TypeScript dict of dicts plus a ~30-line React context
  • hook (useI18n()).

Neither needs a build step, a message extractor, or a new dependency.

Backend: bober_bbq/utils/i18n.py

from bober_bbq.utils.i18n import t

text = t("order.status.confirmed", locale, number=order.display_number())

• TRANSLATIONS is a dict[locale][key] -> template string ({placeholder} syntax, filled in with str.format(**kwargs)).
• SUPPORTED_LOCALES = ("uk", "en"); DEFAULT_LOCALE = "uk".
• normalize_locale(code) maps an arbitrary code (e.g. Telegram's language_code, which can be "en-US", "uk", "ru", etc.) to a supported locale, defaulting to "uk" for anything unrecognized — including a locale we simply haven't added yet.
• t() never raises and never shows a customer a crash: a missing key for a supported locale falls back to uk; a missing key everywhere returns the raw key (ugly, but visible and non-fatal) — both cases log a warning so the gap gets noticed and fixed.

Locale storage: TelegramUser.locale

• New nullable column, default "uk" (see bober_bbq/models.py and the migration in bober_bbq/migrate.py, added via _add_column_if_missing exactly like every other column in that file — safe to run repeatedly, including against the existing production SQLite database).
• Populated once, on first contact only (never overwritten on later visits, so a customer's own future language choice — once there's a settings screen for it — won't be silently reset by their Telegram client language):
  • Bot: bot/services/cart_service.py's get_or_create_user() takes an optional language_code argument, sourced from aiogram's message.from_user.language_code in bot/handlers/start.py.
  • Mini App / Flask API: bober_bbq/api/auth.py's _upsert_user() reads language_code out of the Telegram WebApp initData payload (Telegram includes it in the user JSON automatically).

Menu content: Category.name_en / Product.name_en / Product.description_en / Product.weight_en

Product/category names, descriptions, and the weight/volume field ("300 г" → "300 g") are admin-entered business data, not UI chrome — they live in the database, not in TRANSLATIONS. Each gets an optional nullable ..._en column (bober_bbq/models.py, migrated via the usual _add_column_if_missing in bober_bbq/migrate.py), filled in from the product/category edit forms in the admin panel (Назва EN, Опис EN, Вага/обʼєм EN — labels are Ukrainian since the admin panel itself stays Ukrainian-only, the values typed into them are English). Category.to_dict(locale) / Product.to_dict(locale) return the _en field when locale == "en" and it's actually been filled in, falling back to the Ukrainian value otherwise — an untranslated product just shows its Ukrainian name/weight in the English UI rather than an empty field. bober_bbq/api/menu.py's /categories and /products endpoints take an optional ?locale= query param for this (they have no authenticated user/session to read a stored preference from).

The 14 EU-mandated allergen labels (ALLERGENS in bober_bbq/models.py) are a small, fixed, well-known set, so their English labels live directly in the same dict ((uk_label, emoji, en_label)) rather than needing a database column — Product.allergen_details(locale) picks the right one.

What's translated today (backend)

• bober_bbq/utils/notify_customer.py — every order-status-change message sent to a customer, the cancellation-reason suffix, the pickup-ready address line, and the post-order rating prompt.
• bot/handlers/start.py — the /start welcome message.
• bot/handlers/menu.py — the /menu command's "open the Mini App" hint.
• bot/handlers/contacts.py — the /contacts command and its reply-keyboard button (bot/keyboards.py's main_menu_keyboard(locale) — the button label itself is locale-dependent, so the message filter that recognizes a tap on it matches against every locale's variant, not one fixed string).
• bot/handlers/rating.py — the "already rated" callback answer and all 5 score-specific thank-you messages.
• bober_bbq/api/orders.py — the customer's own order list's status_label (a separate translation namespace, order.status_label.*, from the Ukrainian-only models.ORDER_STATUS_LABELS the admin panel uses), and the cancel/pay error messages.
• bober_bbq/api/checkout.py — every customer-facing validation/business error (empty cart, cafe closed, minimum order amount, invalid payment method, invalid cash-change/time input, the two card-payment-failed Telegram messages, the order-received confirmation) and _contact_field_error's name/phone validation messages.
• bober_bbq/utils/workhours.py's closed_message(locale) and bober_bbq/utils/promo.py's validate_promo_code(..., locale) — shared helpers called from checkout, so both the delivery/pickup/dine-in flows and the promo-preview endpoint get the same localized text.

All of the above resolve locale from TelegramUser.locale — via g.telegram_ user.locale in authenticated Flask routes, or a plain db.session.get (TelegramUser, telegram_id) lookup in bot handlers that don't already have the user loaded. The two unauthenticated menu-browsing endpoints (/api/categories, /api/products) are the only exception — they take ?locale= directly since there's no session to read a stored preference from.

What's still Ukrainian-only by design: admin-authored free text is never translated automatically — a custom force_closed_message, the cafe's phone/address/name in /contacts — same reasoning as menu content: it's business data the admin typed, not UI chrome, shown as written regardless of the reader's locale. Order-item names inside order history are historical snapshots (OrderItem.product_name at the time of purchase) and are also left as originally captured.

Webapp: webapp/src/i18n/

• translations.ts — Record<Locale, Record<string, string>>, Locale = "uk" | "en".
• index.tsx — <I18nProvider> (wraps <App /> in main.tsx) + useI18n() hook returning { locale, setLocale, t }.
  • t(key, vars?) does {placeholder} substitution via a simple regex replace — no ICU plural rules, no framework.
  • Missing key: warns to the console and falls back to uk, then to the raw key — same never-crash philosophy as the backend.
• Initial locale detection (detectInitialLocale()), in priority order:
  1. A previously saved manual choice in localStorage (bober_locale).
  2. Telegram's own client language, Telegram.WebApp.initDataUnsafe.user. language_code (only present inside the real Telegram Mini App).
  3. The browser's navigator.language.
  4. "uk" if nothing else matched or is supported.
• A UA / EN switcher in the app header (App.tsx's LocaleSwitch, .locale-switch in styles.css) lets a customer override auto-detection at any time. Choosing a locale does two things: saves it to localStorage for that browser (so it's stuck to the browser, works offline, and doesn't depend on the API call below succeeding), and fires a fire-and-forget PATCH /api/me/locale (bober_bbq/api/me.py) that persists the choice to TelegramUser.locale server-side — so an explicit in-app choice also applies outside the Mini App session, e.g. the bot's own order-status push notifications, which have no other way to learn about it. A failure to reach that endpoint is silently ignored; the local choice still applies for this browser regardless.

What's translated today (webapp)

Every screen: MenuPage + ProductCard (empty states, quantity stepper, "Add"/currency), CartPage + CartItemRow, CheckoutPage (all three order types end to end), OrdersPage (empty state, payment method/status labels, pay/repeat/cancel buttons, the repeat-order "some items unavailable" message, cancel confirmation dialog), ContactsPage (all labels — the phone/address/hours values themselves are admin-entered business data, see below), ClosedScreen (title + the built-in default message), BottomNav tab labels, and AnnouncementPopup (dismiss button + aria-label). App-level loading-error text and the open/closed header status line are covered too. Currency is shown as "грн" (uk) / "UAH" (en) via a common.currency key.

Menu content (product/category names+descriptions) is fetched per-locale from the backend (see above) — api.categories(locale) / api.products (locale) in api.ts re-fetch whenever the switcher changes, they're not translated client-side.

How to add a new translatable string

Backend: add the key to TRANSLATIONS["uk"] in bober_bbq/utils/i18n.py first (it's the source of truth), then to every other locale dict. Call it as t("your.new.key", locale, **kwargs).

Webapp: add the key to translations.uk in webapp/src/i18n/translations.ts first, then to every other locale. Call it as t("your.new.key", { yourVar: value }) from a component that has const { t } = useI18n();.

In both cases, a key missing from a non-uk locale doesn't break anything — it just falls back to Ukrainian and logs a warning, so translations can be filled in incrementally.

How to add a new language

Backend (bober_bbq/utils/i18n.py):

1. Add the code to SUPPORTED_LOCALES.
2. Add a new top-level dict to TRANSLATIONS with every key uk has.
3. If it should auto-populate from Telegram, no extra work is needed — normalize_locale() already accepts any code Telegram sends once it's in SUPPORTED_LOCALES.

Webapp (webapp/src/i18n/translations.ts):

1. Add the code to the Locale union and SUPPORTED_LOCALES.
2. Add a new top-level object to translations with every key uk has.
3. Add a button for it to the LocaleSwitch component in App.tsx if you want it manually selectable (auto-detection from Telegram/browser works without this).

What's explicitly still Ukrainian-only by design

• The entire admin panel (bober_bbq/templates/admin/*, bober_bbq/admin/*.py) — internal tool for Ukrainian staff, not part of this effort at all, now or later (per explicit scope decision).
• Admin-authored free text, always, regardless of locale: cafe name/phone, a custom force_closed_message, an announcement banner message. These are business content the admin typed, not UI strings — same reasoning as menu content, and the same fix (an optional _en field) would apply if a client ever wants them bilingual too. Address is the one exception: Setting["address_en"] (optional, filled in from Адмінка → Налаштування → Заклад) is used in place of address when locale == "en" and it's non-blank — same opt-in fallback as Product.name_en. Covers every place the cafe's own address is shown to a customer: /api/settings (Mini App contacts screen + the closed screen), the bot's /contacts command, and the pickup-ready notification's address line.
• Historical order-item names in order history — OrderItem.product_name is a snapshot of the product's name at the time of purchase, shown as originally captured rather than re-translated after the fact.
• Product/category translations are opt-in per item — an admin who hasn't filled in name_en/description_en for a given product just sees it fall back to Ukrainian in the English UI; nothing forces translating the whole menu before English can be used at all.

Open decisions for a human

• Which languages to prioritize beyond English — Russian is the other obvious candidate given the customer base, but was deliberately not added here to avoid making a language-priority call that's a business decision, not a technical one.
• Whether cafe name/phone/custom messages should ever be bilingual — would need the same _en-field treatment as address/menu content; not done here since it wasn't asked for and these rarely need translation in practice.
• Machine-translating existing menu items in bulk — right now filling in name_en/description_en is a manual per-product admin task. Auto- translating via an API (DeepL/Google Translate) was considered and deliberately not built: mistranslating a dish's name or, worse, an allergen-relevant detail in its description is a real safety concern for food, not just a cosmetic one — manual review stays the safer default.