Laraue.Apps.LearnLanguage — open-source Telegram-бот для изучения словарного запаса на нескольких языках. В этой статье разбираем архитектуру, технические решения и детали реализации — пригодится, если вы делаете Telegram-бота на C#, проектируете пайплайн с ИИ-переводом или просто хотите посмотреть, как устроено работающее в продакшене приложение для изучения языков.
Рабочий бот — @learn_lang_bot.
Стек технологий
| Слой | Технология |
|---|---|
| Язык | C# |
| Фреймворк | .NET 10 |
| Бот-фреймворк | Telegram.NET |
| AI-перевод | Ollama (локальный LLM-инференс) |
| Формат данных | JSON (слова и переводы) + EF Core миграции |
| Лицензия | MIT |
Проект — монорепозиторий с двумя запускаемыми приложениями и общим слоем доступа к данным.
Структура репозитория
src/
Laraue.Apps.LearnLanguage.Host/ # Telegram-бот (web API хост)
Laraue.Apps.LearnLanguage.AutoTranslator/ # Консольное приложение для AI-перевода
Laraue.Apps.LearnLanguage.DataAccess/ # Общий EF Core контекст, миграции, seed-данные
tests/
Laraue.Apps.LearnEnglish.IntegrationTests/
Оба приложения используют общий проект DataAccess, в котором лежат схема БД, миграции и JSON-файлы со словами.
Приложение 1: TelegramApiHost
Основное приложение — .NET 10 Web API, которое обрабатывает входящие Telegram-апдейты через Telegram.NET. В режиме локальной разработки используется long-polling, в production — webhook.
Команды и контроль доступа
Команды разделены на две группы:
- Публичные — доступны всем пользователям (запуск квиза, просмотр слов, настройки, статистика прогресса)
- Админские — ограничены настроенным списком ID администраторов (например, принудительная перезагрузка данных, просмотр состояния)
Это стандартный паттерн для Telegram-ботов: middleware-слой сверяет update.Message.From.Id со списком админов, прежде чем передать апдейт нужному обработчику.
Логика квиза
Сессия квиза загружает 20 слов за раунд. Алгоритм выбора слов поддерживает баланс между тремя группами:
- Слова, которые пользователь ещё не встречал
- Слова, пройденные недавно (краткосрочное закрепление)
- Слова из старых сессий (проверка долгосрочного запоминания)
Получается упрощённое интервальное повторение (SRS) без полноценного SRS-планировщика. Слова, на которые был дан неверный ответ, возвращаются в последующие раунды.
Выбор языковой пары
При первом использовании бот предлагает выбрать языковую пару. Выбор сохраняется в настройках пользователя в БД, чтобы не спрашивать каждый раз.
Приложение 2: AutoTranslator
AutoTranslatorApp — самостоятельное консольное приложение, которое сканирует translations.json в поисках слов без переводов на один или несколько языков и заполняет их через локально запущенный Ollama.
Пайплайн перевода
translations.json
↓
Найти слова, где translation[language] == null
↓
Отправить в Ollama (локальный LLM)
↓
Записать результат обратно в translations.json
↓
Создать EF Core миграцию
↓
Применяется автоматически при следующем старте приложения
Использование локального LLM (через Ollama) вместо платного API обнуляет стоимость переводов и убирает зависимость от сети при массовых прогонах. Переводы также можно исправить вручную — просто отредактировав translations.json.
Ранние версии использовали Google Translate API (добавлен в июне 2024 года). Переход на Ollama произошёл в августе 2025-го: это дало более высокое качество контекстных переводов и убрало зависимость от API-ключей.
Модель данных
Файлы слов и переводов
Все данные о словах хранятся в JSON-файлах внутри проекта DataAccess. Это осознанное архитектурное решение — данные становятся:
- Версионированными вместе с кодом
- Удобными для Pull Request — любой может добавить слова или исправить переводы через GitHub
- Аудируемыми — полная история каждого изменения в git
Два ключевых файла:
translations.json — основной список слов. Каждая запись содержит английское слово, уровень CEFR, связанные темы и словарь переводов с языковым кодом в качестве ключа:
{
"word": "resilient",
"cefr": "B2",
"topics": ["personality", "general"],
"translations": {
"ru": "устойчивый",
"de": "belastbar",
"fr": null
}
}
Значение null означает для AutoTranslatorApp, что перевода нет и его нужно сгенерировать.
languages.json — поддерживаемые языковые пары. Чтобы добавить язык, достаточно добавить сюда запись и создать миграцию EF Core.
База данных
Данные из JSON-файлов загружаются в реляционную БД через EF Core. При каждом старте хост проверяет наличие новых записей в JSON и применяет их. Деплой новых слов — просто выкатить новую сборку, никаких ручных SQL-скриптов.
Добавление слов и языков
Порядок действий для контрибьюторов описан в README репозитория.
Добавить слова
- Отредактировать
translations.json - Создать миграцию:
cd src && dotnet ef migrations add MigrationName \
-p Laraue.Apps.LearnLanguage.DataAccess \
-s Laraue.Apps.LearnLanguage.Host -v
- Новые переводы применятся автоматически при следующем запуске.
Добавить язык
- Отредактировать
languages.json - Выполнить ту же команду создания миграции.
Больше никаких изменений в коде не нужно — пайплайн переводов, режим квиза и выбор языка подхватят новые языки автоматически.
Локальная разработка
Бот локально запускается в режиме long-polling (публичный URL и webhook не нужны):
- Создайте бота через @BotFather и скопируйте токен.
- Создайте
appsettings.Development.jsonв проектеLaraue.Apps.LearnLanguage.Host:
{
"Telegram": {
"Token": "ваш_токен_бота"
}
}
- Запустите
Laraue.Apps.LearnLanguage.Host. - Напишите боту
/startв Telegram.
Для AutoTranslator также потребуется локально запущенный Ollama с подходящей моделью.
CI/CD
Репозиторий содержит GitHub Actions воркфлоу (.github/workflows/) для автоматической сборки и прогона тестов. Интеграционные тесты находятся в tests/Laraue.Apps.LearnEnglish.IntegrationTests/.
История развития проекта
Часть нынешних решений объясняется тем, как развивалась архитектура:
| Дата | Изменение |
|---|---|
| Янв 2023 | Первая версия: просмотр списка слов + ручная кнопка «отметить как выученное» |
| Янв 2024 | Добавлен просмотр по уровням CEFR |
| Фев 2024 | Архитектура переработана для поддержки нескольких языковых пар |
| Июн 2024 | Добавлен AutoTranslatorApp (Google Translate API) |
| Авг 2025 | Переход на Ollama для локального AI-перевода |
| Сен 2025 | Добавлен режим квиза |
| Фев 2026 | Релиз v1.0.0 — квизы по уровням CEFR |
Планы на будущее
- Гибкая фильтрация квиза — ограничение пула слов по теме или уровню CEFR
- Контекстные предложения от AI — объединение недавно изученных слов в короткие тексты для долгосрочного запоминания
- Тематические паки слов — наборы для конкретных жизненных ситуаций: аэропорт, ресторан, транспорт
Как помочь проекту
Проект распространяется под лицензией MIT и открыт для контрибьюций. Самый простой вклад — редактирование translations.json для добавления недостающих переводов или исправления существующих: знание C# не требуется. А архитектура достаточно чистая и изолированная, чтобы добавить новую команду бота или расширить движок квиза было несложно.
- Репозиторий: github.com/Laraue/Laraue.Apps.LearnLanguage
- Бот: @learn_lang_bot
- Сайт: laraue.com/learn-language-bot