Назад к статьям
Статья

Telegram-бот для изучения языков на C# и .NET 10 — архитектура и технические решения

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 репозитория.

Добавить слова

  1. Отредактировать translations.json
  2. Создать миграцию:
cd src && dotnet ef migrations add MigrationName \
  -p Laraue.Apps.LearnLanguage.DataAccess \
  -s Laraue.Apps.LearnLanguage.Host -v
  1. Новые переводы применятся автоматически при следующем запуске.

Добавить язык

  1. Отредактировать languages.json
  2. Выполнить ту же команду создания миграции.

Больше никаких изменений в коде не нужно — пайплайн переводов, режим квиза и выбор языка подхватят новые языки автоматически.


Локальная разработка

Бот локально запускается в режиме long-polling (публичный URL и webhook не нужны):

  1. Создайте бота через @BotFather и скопируйте токен.
  2. Создайте appsettings.Development.json в проекте Laraue.Apps.LearnLanguage.Host:
{
  "Telegram": {
    "Token": "ваш_токен_бота"
  }
}
  1. Запустите Laraue.Apps.LearnLanguage.Host.
  2. Напишите боту /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# не требуется. А архитектура достаточно чистая и изолированная, чтобы добавить новую команду бота или расширить движок квиза было несложно.