GenauLingua — learn any of ten languages from the one you speak

A production Telegram bot for vocabulary learning (A1–C2) — ten languages in any pair, six games mixed inside every lesson, natural-voice audio for every word, speech recognition, adaptive spaced repetition and a monthly competition with medals, crowns and titles. Free and ad-free.

🤖 Live bot: t.me/GenauLingua_bot

---

Overview

GenauLingua is a real, deployed Telegram bot. Version 2.0 went live on 14 October 2026: the bot grew from one game and one language (German) to six languages in any combination, six games, full pronunciation and speech practice. Version 2.1 "Retention" followed on 16 October 2026: it is about bringing people back — 79% of everyone who ever studied had never studied two days in a row. Version 2.2 "Ten languages" went live on 18 October 2026: Italian, Spanish, French and Czech, a new onboarding, reports on every answer and a monthly competition.

	2.0 (14 Oct)	2.1 (16 Oct)	2.2 (live, 18 Oct)
Languages to learn	6, any pair — 30 directions	same	10, any pair — 90 directions
Interface languages	6	same	10
Games	6, mixed in every lesson	I build simpler at A1–A2	same
Audio	every word and example, natural voice	same	two voices per new language, female or male by choice
First lesson	7 questions	7 easy cards from the 60 most common short words	7 questions: I read · I listen · I recall, then a 3-pair board
Onboarding	—	—	own language (flags) → language to learn, two taps; /language; reminders on by default for newcomers
Messages from the bot	daily reminder to everyone who has them on	one dispatcher: about the person, ≤ 1 a day, stops after 14 days, 10% control group	same
Day streak	in the learner's time zone	+ weekly freeze, milestones 3/7/14/30	same; 🔥 on the home screen
Ranking	per learning language, medals per language	same	Month · All time · Your language; medals for the shared month (3+ lessons), a crown per language, titles from glory, a 12-piece collection
Reports	from the lesson summary	same	under every answer: translation / example / audio
Restarts	interrupted lessons	lessons survive a restart (Redis)	same

Production numbers (18 Oct 2026, at the 2.2 release)

Metric	Value
Registered users	255
Lessons played / questions answered (all time)	2,513 / 29,932
Word base	12,902 entries × 10 languages, A1–C2, 20 topics; 9,159–12,372 distinct words per language after merging duplicates
Pronunciation clips	197,682 needed by the code, all on disk (153,738 added in 2.2)
Test suite	1,408 tests

The release was rehearsed on a copy of the live database inside the server; on the real run 19 tables of people's data were fingerprinted before and after — identical. Downtime was 13 minutes, of which the steps themselves took 2 min 17 s.

---

What's new in 2.2 — Ten languages

Change	Why
Italian, Spanish, French, Czech — to learn and as interface languages. All 12,902 entries got a translation and an example in each; each language got two voices (female and male, chosen in Settings → Audio). The 4,000 most frequent words per language and the whole interface were proofread for natural phrasing (109 + 47 fixes).	Requests from learners.
Onboarding in two taps: your own language (with flags) → the language to learn, a back arrow on both screens, /language and a command menu set from code.	A real learner picked the wrong language and could not change it.
First lesson: I read · I listen · I recall, twice each, then a 3-pair board — so a newcomer sees the bot's range at once. Reminders switch on by themselves for newcomers at the hour they joined (10:00–20:00), with the 10% control group kept.	Fewer questions after the first lesson; variety from the first minute.
Reports under every answer — translation, example or audio, one or several; +15 points for a confirmed report.	Reporting from the summary meant remembering the word.
Competition: tabs Month (everyone) · All time · Your language; medals 🥇🥈🥉 for the shared month with 3+ lessons and a single winner per place; a 👑 crown per language for the next month (when 3+ people have 3+ lessons); titles 🌱 → 🌌 from glory (medals and achievements); a 12-piece collection; "↑ place this month" and a monthly record in the lesson summary. "You were overtaken" exists but is off (COMPETITION_NUDGES).	A lone learner of a new language would have taken gold after one lesson; status did not accumulate.
Release notes page in all ten languages, linked from the broadcast with the learner's language preselected.	One message, every learner's language.

---

What's new in 2.1 — Retention

Every item below answers a number or a case from production on 15 October 2026.

Change	Why
Engagement messages replace the old reminders. After a break the bot writes on day 1, 3, 7 and 14, then stops; a newcomer who never started gets an invitation on day 1, 3 and 7. Those who turned reminders on get them at their own hour while the break is ≤ 2 days. Never more than one a day, at least 12 h apart, daytime only. Each message is about the person — their streak, their numbers, one of their words under a spoiler as a mini-question. "Don't send" is final; blocking the bot counts as "don't send".	The old daily reminder was "a note about the bot instead of about the person"; 24 people blocked the bot after the 2.0 reminder wave.
Control group and outcomes. 10% of people get no ladder messages; every decision is logged. Admin → "Messages" shows who came back within a day, who tapped the button, who unsubscribed or blocked — next to the control group.	"Track it — so we know whether it works or harms."
Easy first lesson: 7 cards from the 60 most frequent short words (≤ 10 letters, single word), respecting the chosen topic.	21 of 32 abandoned lessons were abandoned on question 0–2; a Polish newcomer got "mieć na myśli" as the very first word.
Streak: one missed day a week is frozen, not reset; milestones at 3, 7, 14 and 30 days; 🔥 next to the name in the ranking from 3 days.	Streak mechanics shown to work elsewhere; approved by the owner.
Known words faster: a word answered correctly at first sight is learned after one more correct check (two in a row instead of three). There is no "I know this" button — an accidental tap is a guess.	Learner feedback: "I don't need to prove it three times."
I build at A1–A2: phrases of up to 5–6 words, one trap, never another form of a word in the phrase (gehe/geht).	I build: 44% correct overall, 25% at A1, ~51 s per answer.
I speak: the card says where to record a voice message (hold 🎤 at the bottom right of Telegram).	Two voice attempts in a whole day of production.
Lessons in Redis: a deploy or restart no longer interrupts a lesson; an answer caught mid-restart does not lock the question.	Restarts on 15 October twice cut people's lessons.
Journey log: taps, questions, voice attempts (what was heard, similarity, attempt number), skips and level changes — app/scripts/journey.py --user <hash> --day <date>.

---

What the learner gets

One button, six games

A lesson is 15 questions behind a single "Learn words" button. Games alternate inside the lesson — the learner never has to choose:

Game	Task	Skill
📖 I read	word → pick the meaning	recognition
💭 I recall	meaning → pick the word	recall
🎧 I listen	audio → pick the word	listening
🎤 I speak	say the word in a voice message	production, pronunciation
🧩 Find the pairs	match 5 words with 5 meanings on a board	consolidation
🧱 I build	assemble the example sentence from word tiles with traps	grammar, word order

Games unlock per word: a new word always arrives as a card; recall and listening open after one correct answer, speaking and sentence building after two. A newcomer's first lesson is 7 questions — I read, I listen and I recall twice each, then a 3-pair board; from the second lesson the regular mix takes over (15 questions, one of them a 5-pair board).

I build adds grammatical twins as traps (der/den/dem, ist/sind, er/sie) — one at A1–A2 with phrases of up to 5–6 words, 2–5 at higher levels — never gives the first word away with a capital letter, and only uses words at or below the learner's level. The result screen marks every word ✓/✗, lists what was extra and what was missing, and says "right words, different order" when only the order differs.

I speak uses self-hosted speech recognition (faster-whisper on the bot's own server): two attempts, then the question is skipped without a penalty — a microphone problem is not a mistake. The card says where to record (hold 🎤 in Telegram's input field). Listening and speaking both have a Skip button for when sound is not an option.

Spaced repetition that adapts

• Words return after an hour (after a mistake), a day, 3 days, a week, 3 weeks, 2 months.
• Learned = three correct answers in a row on different days; a word answered correctly at first sight needs only one more correct check.
• The bot offers the next level at ≥ 90% accuracy (and asks again 5 lessons after a "no").
• A learning goal (work, travel, living abroad, study) puts topic words first.
• Modes: by level, by topic, the whole base, difficult words; mistakes can be repeated right after the lesson.

Audio

Every word and every example sentence is voiced with a natural voice; the learner can pick a female or a male voice (Settings → Audio). All clips the code can ask for are generated in advance and stored on the server; on first use a clip is uploaded once and then cached as a Telegram file_id — instant playback, no server bandwidth. Listening questions use a neutral clip title so the answer is not printed on the player. A slow reference clip is one tap away in the speaking game.

Motivation

• A monthly competition with three tabs: Month (everyone), All time, and Your language. Medals 🥇🥈🥉 go to the top three of the shared month with at least 3 lessons (+100 / +50 / +25 all-time points; places 4–10 get +10); a 👑 crown goes to the best learner of each language for the next month when 3+ people have 3+ lessons. Medals and achievements give glory, glory gives a title (🌱 Sprout → 🌳 → 🌙 → 🪐 → ☀️ → a secret sixth). A collection of 12 achievements lives in the statistics; the lesson summary shows "↑ place this month" and a monthly record.
• Points reward effort: answer +1, I recall +1, a board pair at first try +1, listening +2, speaking +3, I build +3, lesson +10, learned word +3, streak up to +10, accuracy bonus above 60%.
• Day streak counted in the learner's own time zone, with one frozen day a week and milestones at 3 / 7 / 14 / 30 days in the lesson summary; 🔥 on the home screen from 3 days.
• Engagement messages — after a break of 1, 3, 7 and 14 days (then silence until the learner returns), or daily at the learner's own hour for those who asked. Each one is about the person: their streak, their progress, one of their own words as a mini-question. At most one a day; "don't send" is final.
• Report a mistake under any answer — translation, example or audio; each confirmed report earns +15 points.

Statistics

A home screen with one skill bar per game shows the gap between skills ("I recognise it in writing but not by ear"); the detailed view adds learned / in progress / difficult, grammar accuracy, lesson history and overall progress.

For the owner

An admin panel with analytics, cohorts, churn, "started / completed" lessons, "came back today out of those active in the last 7 days", per-language broadcasts and report moderation; a "Messages" report compares people who got an engagement message with the control group. A per-person journey log answers "where exactly did this person stop". Release notes go out in every learner's interface language, and the bot sends follow-up reports on how many came back.

---

Architecture

app/
├── bot/
│   ├── handlers/
│   │   ├── quiz/        # one module per concern:
│   │   │   ├── lesson.py        # lesson flow: start, next question, repeat mistakes
│   │   │   ├── lesson_state.py  # FSM keys, the per-chat lock, restart-safe answer claims
│   │   │   ├── question.py      # question and answer screens
│   │   │   ├── choice.py        # 📖 💭 🎧 answers by button
│   │   │   ├── listen.py        # 🎧 audio and its fallback to text
│   │   │   ├── speech.py        # 🎤 voice answers, slow reference, skip
│   │   │   ├── match.py         # 🧩 pairs board
│   │   │   ├── build.py         # 🧱 sentence building
│   │   │   ├── summary.py       # lesson summary, praise, level offer
│   │   │   ├── expired.py       # buttons of a lesson the bot no longer remembers
│   │   │   └── home / stats / settings / report / help
│   │   ├── leaderboard/  # monthly, all-time, tables
│   │   ├── reminders.py, start.py, admin.py
│   ├── routers.py       # the router set and its ORDER — one source for bot and tests
│   └── keyboards/, states.py
├── services/            # business logic: quiz engine, SRS, scoring, leaderboards,
│                        # build_service, speech_check, audio, word groups,
│                        # nudge_plan / nudge_texts (who gets which message), journal
├── database/            # SQLAlchemy 2.0 models (19 tables), enums, async session
├── schedulers/          # engagement messages (nudges.py), monthly season rollover
├── locales/             # uk / en / de / pl / cs / es / fr / it / tr / ru
├── testing/             # fake Telegram + the real dispatcher, shared by tests and tooling
├── scripts/             # 127 tools: acceptance suites, deploy, wordbase, TTS, reports,
│                        # journey log, message forecast
└── main.py

alembic/                 # 49 migrations
tests/                   # 1,408 tests
deploy/                  # preflight and backup scripts

About 36k lines of application code (including ten locales), 30k lines of tooling, 21k lines of tests.

Design principles

• One source per decision. Answer channels, their prices and unlock thresholds come from one enum (QuizChannel, counted_channels()); the scoring formula lives in MonthlyStats.calculate_monthly_score(); who is ranked in a month is one predicate (ranked_in_month). Every one of these was once duplicated, and every duplicate drifted.
• Rule, not list. Progress columns are merged by a rule read from the table itself, so a new column cannot be silently dropped by a rebuild.
• Handlers stay thin; learning logic lives in services/ and is tested without Telegram.
• Fully async: aiogram 3 + SQLAlchemy 2.0 + asyncpg.
• Idempotent answers: a per-chat lock claims each question exactly once — double taps never score twice; a claim left by a process that died mid-answer is released.
• One sender for every bot-initiated message: one rule (nudge_plan.decide) decides who gets what; a conditional UPDATE claims each send, so two processes never send twice.

Verification beyond unit tests — every change is also checked by acceptance suites that play the real dispatcher on the real word base:

Suite	What it proves
audit_round --full	38 lesson compositions played to the end: numbering, counters, mistakes, reports, channels and points agree
verify_quiz_channels	every game builds correctly in every language pair
verify_quiz_round --full	960 lessons, 14,400 questions across all ten languages — every question has a word or a sound
audit_accounting	17 checks across five accounting layers: answers ↔ lessons ↔ progress ↔ month ↔ all-time
verify_buttons	no button leads nowhere, menus work in every interface language
release_snapshot --compare	a deploy loses nothing: users, progress, answers, awards
nudge_forecast	who would get which engagement message, hour by hour — nothing is sent

Tests are written "break it on purpose": a fix is accepted only after the test was seen to fail with the fix removed.

---

Tech Stack

Layer	Technology
Language	Python 3.11
Telegram	aiogram 3.15 (async)
Database	PostgreSQL 16, SQLAlchemy 2.0 async, asyncpg, Alembic
Lesson state	Redis 7 (append-only), aiogram RedisStorage
Speech recognition	faster-whisper (CTranslate2, int8, on CPU)
Text-to-speech	edge-tts
Scheduling	APScheduler
Config	Pydantic Settings
Errors	Sentry (optional)
Deployment	Docker Compose on Hetzner (EU)

---

Getting Started

git clone https://github.com/Kanaki-K/GenauLingua.git
cd GenauLingua

cp .env.example .env      # BOT_TOKEN, ADMIN_USER, database credentials
docker compose up -d --build

Migrations run automatically on container start. The speech-recognition model is baked into the image at build time, so the first voice answer does not wait for a download.

Run the tests (a PostgreSQL test database on port 5433 is expected; override with TEST_DATABASE_URL):

pytest

Releasing to production

DEPLOY.md is the step-by-step procedure used for the 2.0, 2.1 and 2.2 releases: preflight, backup, snapshot, migrations, word-base transfer, the "nothing lost" comparison before the accounting repair, and rollback. Each release is rehearsed on a copy of the production database first; since 2.2 the rehearsal runs inside the server on a temporary database, so no copy of people's data ever leaves it. For 2.1 it adds a forecast of who gets which message in the next 48 hours (nudge_forecast) — run after the migration and before the bot starts, so a release never sends a wave of messages. Release notes go out with send_release_notes — every learner in their interface language, resumable without duplicates. Releases are tagged v2.0, v2.1, v2.2.

Working notes

The project notes are in Russian, the owner's language: STATE.md · ROADMAP.md · REWARDS.md (the competition) · LANGUAGES_PLAN.md · WORDBASE_REVIEW.md · AUDIO_STORAGE.md · DEPLOY.md.

Configuration

All secrets are supplied via environment variables in .env; no secrets are stored in the repository. See .env.example.

---

What This Project Demonstrates

• Product engineering end to end — from a one-game bot to a six-game, ten-language product, deployed to real users with zero data loss (verified row by row).
• Learning design — spaced repetition, per-word game unlocking, a difficulty ladder by CEFR level, effort-based scoring.
• Speech and audio — self-hosted speech recognition with word-boundary matching (so "das Ei" is not heard inside "Bleistift"), and a TTS pipeline that produced and verified ~198,000 clips in two voices.
• Internationalisation — ten languages with language-specific correctness (Turkish İ/ı, German noun capitalisation, Polish impersonal politeness, French non-breaking spaces, formal address everywhere — Sie, vous, usted, Lei, Vy).
• Data integrity — five-layer accounting with an automated audit and an idempotent repair.
• Operations — rehearsed releases, backups, rollback tags, firewall and fail2ban on the server, scheduled broadcasts and follow-up reports; lessons survive restarts.
• Retention as an experiment — every engagement message is logged with its outcome next to a fixed 10% control group, so "it works or it harms" is measured, not assumed.

---

Privacy

The bot processes only what it needs to run (Telegram ID, learning progress, preferences). Details: PRIVACY_POLICY.md.

License

Built as an independent product. The bot is free to use and runs without ads.