Forem: Muazu Idris Y.

Building MultiLingo: An AI Translation Agent with Telex Integration

Muazu Idris Y. — Mon, 03 Nov 2025 18:36:07 +0000

How I built an intelligent translation agent that speaks 25+ languages and integrates seamlessly with Telex.im

🎯 The Challenge

Language barriers are everywhere. Whether you're chatting with international friends, reading foreign content, or building global applications, translation is essential. I wanted to create something more than just another translation API—I wanted to build an intelligent agent that you could talk to naturally, like a multilingual friend who's always ready to help.

Enter MultiLingo Agent: a conversational AI that combines string analysis with powerful translation capabilities, all accessible through a simple chat interface on Telex.im.

🚀 What is MultiLingo?

MultiLingo is an AI-powered translation agent that:

Translates text to 25+ languages instantly
Detects languages automatically
Analyzes strings (palindromes, character frequency, word count, etc.)
Understands natural language - no rigid commands needed
Integrates with Telex.im - chat with it like a real person

Try it yourself:

"Translate 'hello world' to Spanish"
"What language is 'bonjour le monde'?"
"Is 'racecar' a palindrome?"

The agent understands and responds intelligently!

🏗️ The Tech Stack

I built MultiLingo using modern, production-ready tools:

Backend

FastAPI (Python) - Lightning-fast API framework with automatic documentation
deep-translator - Multi-provider translation library
langdetect - Automatic language detection

Database

PostgreSQL (Neon Cloud) - Stores translations, conversations, and analytics
SQLAlchemy - ORM for elegant database interactions

Deployment

Railway - Seamless deployment with automatic SSL
Telex.im - Chat platform for agent interactions

Why This Stack?

FastAPI was perfect because:

Automatic API documentation (Swagger UI)
Built-in data validation with Pydantic
Async support for performance
Easy webhook integration

Neon PostgreSQL gave me:

Zero-config cloud database
Auto-scaling (scales to zero when idle)
Built-in branching for testing
Free tier perfect for side projects

🛠️ Building Process: From Idea to Integration

Phase 1: Core Translation Service

First, I built the translation engine. Initially, I tried googletrans, but hit async/await issues:

# ❌ This didn't work - async issues
from googletrans import Translator
translator = Translator()
result = translator.translate("hello", dest="es")
# Error: 'coroutine' object has no attribute 'text'

Lesson learned: Always check if libraries require async/await before diving in!

Solution: Switched to deep-translator - synchronous, reliable, production-ready:

# ✅ This works perfectly
from deep_translator import GoogleTranslator

translator = GoogleTranslator(source='auto', target='es')
result = translator.translate("hello world")
# Output: "Hola Mundo"

Phase 2: Building the Intelligence

The real magic is in intent detection. I wanted users to chat naturally, not memorize commands.

Example of intent detection:

def detect_intent(message: str):
    # "Translate 'hello' to Spanish"
    match = re.search(r'translate\s+["\']?(.+?)["\']?\s+to\s+(\w+)', message)
    if match:
        return "translate", {
            "text": match.group(1),
            "target_language": match.group(2)
        }
    # ... more patterns

This allows the agent to understand:

"Translate X to Y"
"How do you say X in Y?"
"What is X in Y?"
Even just "X in Y"

Pro tip: Regular expressions are your friend for natural language parsing. Start simple, iterate based on real user messages.

Phase 3: Database Design

I created four tables to track everything:

1. strings - Original string analysis
2. translations - Translation history with caching
3. telex_conversations - Chat history for context
4. agent_analytics - Usage metrics

Smart caching strategy:

# Check if we've translated this before
existing = get_translation(db, text, target_language)
if existing:
    return existing  # Instant response!

# Otherwise, translate and cache
result = translate_text(text, target_language)
store_translation(db, result)

This makes repeated translations lightning-fast!

Phase 4: Telex Integration

The Telex webhook is beautifully simple:

@app.post("/webhook/telex")
def telex_webhook(payload: TelexWebhookPayload, db: Session = Depends(get_db)):
    # 1. Receive user message
    user_message = payload.message

    # 2. Process with intelligent handler
    response = process_chat_message(user_message)

    # 3. Store conversation for context
    create_telex_conversation(db, payload.user_id, user_message, response)

    # 4. Return response to Telex
    return TelexResponse(message=response["message"], success=True)

The beauty: Telex handles all the chat UI, authentication, and message delivery. I just process and respond!

💡 Key Learnings & Challenges

Challenge 1: Async vs Sync Libraries

Problem: Initial translation library required async/await, but my API was synchronous.

Solution: Found deep-translator which is synchronous by design. Always read the docs thoroughly!

Challenge 2: Natural Language Understanding

Problem: Users phrase requests differently:

"Translate hello to Spanish"
"How do you say hello in Spanish?"
"What is hello in Spanish?"

Solution: Multiple regex patterns with fallbacks. Test with real user messages and iterate.

# Support multiple patterns
patterns = [
    r'translate\s+(.+?)\s+to\s+(\w+)',
    r'how\s+(?:do\s+)?(?:you\s+)?say\s+(.+?)\s+in\s+(\w+)',
    r'what\s+(?:is|\'s)\s+(.+?)\s+in\s+(\w+)',
]

Challenge 3: Language Code Normalization

Problem: Users might say "Spanish", "spanish", "es", "spa", "span"...

Solution: Flexible normalization function:

def normalize_language_code(lang_input: str) -> str:
    lang_lower = lang_input.lower().strip()

    # Check if it's already a code
    if lang_lower in LANGUAGE_CODES:
        return LANGUAGE_CODES[lang_lower]

    # Check for partial matches
    for name, code in LANGUAGE_CODES.items():
        if name.startswith(lang_lower[:3]):
            return code

    raise ValueError(f"Unrecognized language: {lang_input}")

Now "spanish", "Spanish", "span", and "es" all work!

Challenge 4: Context-Aware Conversations

Problem: Users expect the agent to remember previous messages:

User: "Translate 'hello' to Spanish"
User: "Now translate it to French" ← What is "it"?

Solution: Store conversation history and pass context:

# Get recent conversation history
history = get_telex_conversation_history(db, user_id, limit=5)
context = {"last_text": history[0].user_message if history else None}

# Process with context
response = process_chat_message(message, context)

📊 Results & Features

What MultiLingo Can Do

🌍 Translation (25+ Languages)

User: "Translate 'good morning' to German"
Agent: "✅ Translation Complete!
        Original (english): good morning
        German: Guten Morgen

        📊 Analysis:
        - Length: 12 characters
        - Words: 2
        - Palindrome: No ✗"

🔍 Language Detection

User: "What language is 'hola mundo'?"
Agent: "🔍 Language Detected!
        Text: hola mundo
        Language: Spanish (es)
        Confidence: 100%"

📊 String Analysis

User: "Is 'racecar' a palindrome?"
Agent: "📊 String Analysis
        Text: racecar

        Properties:
        - Length: 7 characters
        - Words: 1
        - Palindrome: Yes ✓"

💬 Natural Conversation

User: "hello"
Agent: "👋 Hello! I'm MultiLingo Agent!

        I'm here to help you with:
        ✅ Translations (25+ languages)
        ✅ Language detection
        ✅ String analysis

        Try asking me to translate something!"

Performance Metrics

Response Time: < 500ms average
Supported Languages: 25+
API Endpoints: 15+
Success Rate: 99%+ (with error handling)
Caching: Instant repeat translations

🎨 Design Decisions That Made a Difference

1. Modular Architecture

I separated concerns into distinct modules:

translator.py - Pure translation logic
chat_handler.py - Intent detection & responses
crud.py - Database operations
main.py - API endpoints only

Benefit: Each module can be tested independently. Changed translation providers? Only touch one file!

2. Comprehensive Error Handling

Every endpoint has proper error handling:

try:
    result = translate_text(text, target_lang)
    return success_response(result)
except ValueError as e:
    # User error (bad language code, etc.)
    raise HTTPException(status_code=400, detail=str(e))
except Exception as e:
    # System error (translation service down, etc.)
    raise HTTPException(status_code=500, detail="Translation failed")

Benefit: Users get helpful error messages, not stack traces!

3. Automatic API Documentation

FastAPI's Swagger UI is incredible. Every endpoint is auto-documented:

@app.post(
    "/translate",
    response_model=TranslationResponse,
    responses={
        201: {"description": "Translation completed"},
        400: {"description": "Invalid request"}
    }
)
def translate_endpoint(request: TranslationRequest):
    """
    Translate text to target language.

    Example:
        POST /translate
        {"text": "hello", "target_language": "es"}
    """

Benefit: Interactive docs at /docs - test everything in the browser!

4. Smart Caching

Translations are cached by text + language:

translation_id = f"{hash_of_text}_{language_code}"

Benefit: Popular translations (like "hello" → "hola") are instant!

🚢 Deployment Journey

Railway Setup (5 minutes!)

Connected GitHub repo
Added environment variable: DATABASE_URL
Railway auto-detected Python app
Boom! Live in production

Railway's auto-deploy on push is magical. Every GitHub push triggers:

Fresh build
Dependency installation
Database migrations
Zero-downtime deployment

Telex Integration (2 minutes!)

Registered agent on Telex.im
Set webhook URL: https://my-app.up.railway.app/webhook/telex
Tested with messages
Agent responded instantly!

The integration was surprisingly smooth. Telex's webhook format is clean and well-documented.

🎓 What I Learned

Technical Lessons

Read the docs first - Saved hours by choosing the right libraries upfront
Start simple, iterate - Begin with basic translation, add features gradually
Test early, test often - Separate test files for each module
Error handling matters - Users appreciate clear error messages
Cache aggressively - Translations are perfect for caching

Product Lessons

Natural language beats commands - "Translate hello to Spanish" > /translate hello es
Context matters - Users expect the agent to remember previous messages
Response formatting is key - Emoji and formatting make responses delightful
Examples help - The "help" command with examples reduces support questions
Fast responses win - Sub-second responses feel magical

Integration Lessons

Webhooks are simple - Telex integration took minutes, not hours
Documentation is king - Good docs make integration painless
Test webhooks locally first - Use ngrok or similar tools
Log everything - Railway logs were invaluable for debugging
Start with one platform - Master Telex before adding Discord, Slack, etc.

🔮 Future Enhancements

I'm planning to add:

1. Multi-Provider Translation

DeepL for premium quality
OpenAI GPT for context-aware translations
Fallback system for reliability

2. Advanced Features

Voice message translation
Image text extraction (OCR) + translation
Translation memory (learn from corrections)
Batch translation for documents

3. More Integrations

Discord bot
Slack app
Telegram bot
WhatsApp Business API

4. Analytics Dashboard

Most translated phrases
Popular language pairs
User engagement metrics
Translation accuracy feedback

5. Enterprise Features

API authentication with keys
Rate limiting per user
Custom translation glossaries
Team workspaces

🎯 Key Takeaways

For Developers Building Agents:

✅ Choose the right tools - Async vs sync matters

✅ Natural language is hard - Start with patterns, iterate

✅ Context makes agents intelligent - Store conversation history

✅ Error handling is crucial - Fail gracefully with helpful messages

✅ Cache everything you can - Speed matters

For Platform Integrations:

✅ Webhooks are your friend - Simple, reliable, scalable

✅ Test locally first - Use tools like ngrok

✅ Log extensively - You'll need those logs

✅ Read platform docs - They're usually better than you think

✅ Start small, iterate - One platform, then expand

For Product Design:

✅ Users want conversation, not commands

✅ Fast responses feel magical (< 500ms)

✅ Good formatting matters (emoji, line breaks)

✅ Examples reduce friction (show, don't just tell)

✅ Error messages should help, not confuse

💻 Code Highlights

Intent Detection Engine

def detect_intent(message: str) -> Tuple[str, Dict]:
    """Smart intent detection using regex patterns"""
    message_lower = message.lower().strip()

    # Translation patterns
    patterns = [
        r'translate\s+["\']?(.+?)["\']?\s+to\s+(\w+)',
        r'how\s+(?:do\s+)?(?:you\s+)?say\s+["\']?(.+?)["\']?\s+in\s+(\w+)',
        r'what\s+(?:is|\'s)\s+["\']?(.+?)["\']?\s+in\s+(\w+)',
    ]

    for pattern in patterns:
        match = re.search(pattern, message_lower)
        if match:
            return "translate", {
                "text": match.group(1),
                "target_language": match.group(2)
            }

    # Fallback to other intents...

Smart Caching System

def translate_with_cache(text: str, target_lang: str, db: Session):
    """Check cache before translating"""
    # Try cache first
    cached = get_translation(db, text, target_lang)
    if cached:
        return cached  # Instant!

    # Not cached - translate and store
    result = translate_text(text, target_lang)
    store_translation(db, text, result, target_lang)

    return result

Webhook Handler

@app.post("/webhook/telex")
def telex_webhook(payload: TelexWebhookPayload, db: Session = Depends(get_db)):
    """Receive messages from Telex, respond intelligently"""
    # Get conversation history for context
    history = get_conversation_history(db, payload.user_id)
    context = {"history": history}

    # Process with intelligent handler
    response = process_chat_message(payload.message, context)

    # Store conversation
    save_conversation(db, payload, response)

    # Return to Telex
    return TelexResponse(message=response["message"], success=True)

📚 Resources & Links

Live Demo

API Documentation: [Your Railway URL]/docs
Try it on Telex: [Your Telex Agent Link]
GitHub Repository: [Your Repo URL]

Technologies Used

🤝 Contributing

MultiLingo is open source! Contributions welcome:

Add new languages
Improve intent detection
Build new features
Fix bugs

GitHub: [Your Repo URL]

🎉 Conclusion

Building MultiLingo taught me that great AI agents aren't just about the AI - they're about understanding user intent, providing fast responses, and creating delightful interactions.

The combination of FastAPI's speed, Telex's simplicity, and thoughtful design created something that feels magical to use. When users can just type "Translate hello to Spanish" and get an instant, formatted response, that's the experience we should all aim for.

Want to try it? Visit [Your Telex Agent Link] and chat with MultiLingo!

Have questions? Reach out on Twitter [@YourHandle] or open an issue on [GitHub].

Thanks for reading! If you enjoyed this, please share it with others building AI agents. Let's make technology more accessible, one translation at a time. 🌍✨

Built with ❤️ using Python, FastAPI, and AI
November 2025

Building a RESTful API with Real-Time Data — My HNG Internship Project 🚀

Muazu Idris Y. — Sat, 18 Oct 2025 11:42:05 +0000

During the HNG Internship (Stage 0), I built a dynamic RESTful API that integrates with an external service, handles errors gracefully, and returns real-time data using Node.js and Express.

🔗 Live Demo: https://hng-be-s0-production.up.railway.app/me

💻 Source Code: https://github.com/Imuaz/HNG-BE-S0

🧩 The Challenge

The goal was to create an endpoint that:

Returns my profile (email, name, tech stack)
Fetches a random cat fact from an external API
Generates a dynamic UTC timestamp
Handles failures gracefully
Follows a specific JSON format

Example response:

{
  "status": "success",
  "user": {
    "email": "your.email@example.com",
    "name": "Your Full Name",
    "stack": "Node.js/Express"
  },
  "timestamp": "2025-10-17T14:23:45.678Z",
  "fact": "Cats sleep 70% of their lives."
}

Sounds simple, right? But there's more beneath the surface!

⚙️ Tech Stack

Node.js + Express.js
Axios – for API calls
dotenv – for environment variables
CORS middleware
Railway – for deployment
Git & GitHub – for version control

🧠 Implementation Highlights

Project Structure

src/
 ├── routes/profile.js
 └── services/catFactService.js
server.js

server.js → Initializes Express, handles middleware & routes
catFactService.js → Fetches random cat facts with timeout protection
profile.js → Returns user info, timestamp, and a cat fact

Key Features

✅ Modular architecture
✅ Comprehensive error handling
✅ Timeout to prevent hanging requests
✅ Dynamic timestamps (always up to date)

🚀 Deployment

Create a .env file with the following variables:

USER_EMAIL=your.email@example.com
USER_NAME=Your Name
USER_STACK=Node.js/Express

Push your code to GitHub
Deploy on Railway
Add environment variables in the Railway dashboard

5. Visit the `/me` endpoint to test the live API

🧩 Challenges & Lessons

External API failures

→ Solved using Axios timeout + fallback handling
Dynamic timestamps

→ Generated fresh ISO 8601 timestamps per request
Environment setup

→ Used .env for sensitive config, excluded via .gitignore
Deployment

→ Switched to Railway after Render/Vercel restrictions

🧠 Key Takeaways

Always handle API failures gracefully
Keep your code modular and testable
.env files are your friend for managing config
Learn to deploy — DevOps is part of the job!
Testing endpoints early saves hours later

🎯 Conclusion

This project taught me how to design, test, and deploy a real-world API.

If you’re starting with backend development or participating in the HNG Internship, building a project like this is an amazing learning experience.

👉 Check It Out

🔗 Live Demo: https://hng-be-s0-production.up.railway.app/me
💻 GitHub Repo: https://github.com/Imuaz/HNG-BE-S0