A Telegram English learning bot — study irregular verbs, build your word list, and translate on the go.
💬 Community · 🟢 Good First Issues · 🐛 Issues
📋 Prerequisites: Go 1.21+, PostgreSQL 17+, Docker Desktop, Telegram Bot Token (from @BotFather)
# 1. 📥 Clone
git clone https://github.com/Sunagatov/Yulia-Lingo.git && cd Yulia-Lingo
# 2. 🔧 Fill in your credentials
# edit TELEGRAM_BOT_TOKEN and POSTGRESQL_PASSWORD in .env# Start only PostgreSQL
docker compose up -d postgresThen run the app from the terminal:
go run cmd/app/main.godocker compose up -d --buildProduction:
# Fill in .env.prod, then:
docker compose -f docker-compose.prod.yml up -d --build🧪 Run the tests:
go test ./...Yulia Lingo is a Telegram bot that helps you learn English interactively. Practice irregular verbs with quizzes, build a personal vocabulary list, and get instant word translations — all without leaving Telegram.
| 📂 Category | 🔧 Technology |
|---|---|
| 💻 Language | Go 1.21 |
| 🗄️ Database | PostgreSQL 17 |
| 🤖 Telegram | go-telegram-bot-api v5 |
| 📝 Logging | Logrus (structured JSON) |
| 🚢 Deployment | Docker (multi-stage build) |
| Feature | Description | Spec |
|---|---|---|
| 📖 Irregular Verbs | Browsable reference list of 295 verbs organized by letter | docs/features/irregular-verbs.md |
| 📝 My Word List | Save, browse, filter, and rate your personal vocabulary | docs/features/my-word-list.md |
| 🏷️ Browse Mode | Explore words by Category, Letter, POS, Confidence, or Date with smart filters | docs/features/browse-mode-design.md |
| 🤖 AI Categorization | Auto-categorize words with OpenAI (Azure AI compatible) | - |
| 🔍 Translate | Instant word translation with multiple meanings and auto-save | docs/features/translate.md |
| 🌐 Language | Switch between English and Russian interface | docs/features/language.md |
Each feature has a comprehensive spec covering user stories, functional requirements, bot flows, data models, security, and acceptance criteria.
| 🎯 Command | 📝 Description |
|---|---|
/start |
Welcome message and main menu |
/irregular_verbs |
Start irregular verbs practice |
/my_word_list |
View and manage your word list |
/translate |
Translate a word |
/cancel |
Cancel the current operation |
cmd/app/ # Application entry point
internal/
├── config/ # Environment-based configuration
├── database/ # PostgreSQL connection and pooling
├── logger/ # Structured logging
├── telegram/ # Bot setup and update routing
│ └── handlers/ # Command and callback handlers
├── irregular_verbs/ # Irregular verbs domain
├── my_word_list/ # Personal word list domain
├── translate/ # Translation service
└── util/ # Shared utilities
| Variable | Required | Description |
|---|---|---|
TELEGRAM_BOT_TOKEN |
✅ | Token from @BotFather |
POSTGRESQL_PASSWORD |
✅ | Database password |
POSTGRESQL_HOST |
❌ | Defaults to localhost |
POSTGRESQL_PORT |
❌ | Defaults to 5432 |
POSTGRESQL_USER |
❌ | Defaults to postgres |
POSTGRESQL_DATABASE_NAME |
❌ | Defaults to yulia_lingo |
LOG_LEVEL |
❌ | debug, info, warn, error |
IRREGULAR_VERBS_FILE_PATH |
❌ | Path to irregular verbs Excel file |
OPENAI_API_KEY |
❌ | OpenAI/Azure AI API key for categorization |
OPENAI_API_URL |
❌ | API endpoint (default: OpenAI, supports Azure AI) |
OPENAI_MODEL |
❌ | Model name (default: gpt-4o-mini) |
OPENAI_MAX_CALLS_PER_USER_DAY |
❌ | Daily AI limit per user (default: 50) |
OPENAI_MAX_CALLS_PER_USER_HOUR |
❌ | Hourly AI limit per user (default: 10) |
OPENAI_MAX_CALLS_GLOBAL_DAY |
❌ | Global daily AI limit (default: 500) |
See .env for local defaults and .env.prod for the production template.
🎉 Contributions are welcome.
| 🎯 Situation | 🚀 Action |
|---|---|
| 🐛 Found a bug | Open an issue with the bug label |
| 💡 Want a feature | Start a Discussion first |
| 👨💻 Ready to code | Pick a good first issue, comment "I'm on it" |
| 🔧 Big change | Comment on the issue before writing code — tickets may have hidden constraints |
📜 CC BY-NC 4.0 — free for educational and personal use with author attribution. Commercial use requires explicit written permission from the author (zufar.sunagatov@gmail.com).
- 💬 Telegram community: Zufar Explained IT
- 👤 Personal Telegram: @lucky_1uck
- 📧 Email: zufar.sunagatov@gmail.com
- 🐛 Issues: GitHub Issues
❤️