Slango

Where language meets intelligence.

Slango is a full-stack AI translation application supporting 15 languages with automatic language detection, real-time translation, and a modern glassmorphic UI — powered by Hugging Face Helsinki‑NLP models (no Google Cloud credentials required).

API Docs · Report Bug · Request Feature

---

✨ Features

Feature	Description
🔍 Auto Language Detection	Detects the source language automatically — no manual selection needed
🌍 15 Languages Supported	English, Spanish, French, German, Italian, Portuguese, Russian, Japanese, Korean, Chinese, Arabic, Hindi, Bengali, Tamil, Telugu
⚡ Async Translation Engine	Non-blocking async API calls with configurable retry logic and linear backoff
🛡️ Rate Limiting	Per-IP rate limiting (10 req / 60 s by default) to prevent abuse
📋 Request Tracing	Every request gets a unique ID with structured duration logging
🔄 Fallback Mode	Gracefully degrades when API credentials are unavailable (dev-friendly)
🩺 Health Endpoint	/api/v1/health for uptime monitoring and deployment checks
📖 Interactive API Docs	Auto-generated Swagger UI at /docs and ReDoc at /redoc
🎨 Modern UI	Glassmorphic React frontend built with Vite for near-instant HMR

---

🧰 Tech Stack

Backend

Technology	Version	Purpose
Python	3.11	Runtime
FastAPI	0.115	REST API framework
Uvicorn	0.30	ASGI server
Pydantic v2	2.9	Data validation & settings
pydantic-settings	2.5	.env-based config management
pydantic-core	2.23	Pinned for pre-built wheel compatibility
httpx	0.27	Async HTTP client
langdetect	1.0.9	Offline language detection fallback
Google Cloud Translate	v2	Primary translation engine
huggingface_hub	≥0.25	HF Inference API + model downloads
pytest / pytest-asyncio	≥8.0	Test suite

Frontend

Technology	Version	Purpose
React	19	UI framework
Vite	8	Build tool & dev server
Axios	1.15	HTTP client
Vanilla CSS	—	Styling & animations

Infrastructure

Service	Purpose
Render	Backend hosting (Python 3.11, free tier)
Vercel / Netlify	Frontend static hosting
Google Cloud	Translation API (primary)
Hugging Face	Alternative / extended translation models

---

🤗 Using Hugging Face Models (Optional)

Slango's service layer is designed to be swappable. Hugging Face translation models can replace or supplement Google Cloud Translate — ideal for offline inference, cost control, or unsupported language pairs.

Step 1 — Browse Models

Go to the Hugging Face Hub and filter by task:

https://huggingface.co/models?pipeline_tag=translation

Recommended models:

Model	Languages	Size
Helsinki-NLP/opus-mt-en-es	English → Spanish	~300 MB
Helsinki-NLP/opus-mt-en-fr	English → French	~300 MB
Helsinki-NLP/opus-mt-mul-en	Multilingual → English	~300 MB
facebook/nllb-200-distilled-600M	200 languages	~2.4 GB

Step 2 — Create a HF Access Token

1. Create a free account at huggingface.co
2. Go to Settings → Access Tokens → New Token
3. Select Read access and copy the token

Step 3 — Configure the Environment

Add to your backend/.env:

HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
HF_MODEL_ID=Helsinki-NLP/opus-mt-en-es

Step 4 — Inference API (No GPU / No Download Required)

from huggingface_hub import InferenceClient

client = InferenceClient(token="hf_your_token_here")

result = client.translation(
    "Hello, how are you?",
    model="Helsinki-NLP/opus-mt-en-es"
)
print(result.translation_text)  # → "Hola, ¿cómo estás?"

The Inference API runs the model on Hugging Face's servers — no local GPU needed. Free tier supports most Helsinki-NLP models.

Step 5 — Local Inference (Advanced)

Install extra dependencies:

pip install transformers torch sentencepiece

from transformers import pipeline

translator = pipeline("translation", model="Helsinki-NLP/opus-mt-en-es")
result = translator("Hello, how are you?")
print(result[0]["translation_text"])

Requirement: ≥ 4 GB RAM. Use the Inference API for lightweight/serverless deployments.

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• Node.js 18+ and npm
• Google Cloud project with Translation API enabled (or run in fallback mode without credentials)

1. Clone the Repository

git clone https://github.com/KishoreB25/CodeAlpha_Slango.git
cd CodeAlpha_Slango

2. Backend Setup

cd backend

# Create and activate a virtual environment
python -m venv venv

# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Configure Environment Variables

cp .env.example .env

Edit backend/.env:

# ── App ───────────────────────────────────────────────────────
APP_NAME=Slango
APP_VERSION=1.0.0
APP_ENV=development
DEBUG=true

# ── Server ────────────────────────────────────────────────────
HOST=0.0.0.0
PORT=8000

# ── CORS ──────────────────────────────────────────────────────
# Comma-separated list of allowed frontend origins
ALLOWED_ORIGINS=http://localhost:5173

# ── Rate Limiting ─────────────────────────────────────────────
RATE_LIMIT_MAX_REQUESTS=10
RATE_LIMIT_WINDOW_SECONDS=60


# ── Hugging Face Inference API ──────────────────────────────────────────────────────
# Get your free token at: https://huggingface.co/settings/tokens
HF_API_TOKEN=hf_your_token_here
# Models are resolved dynamically by ModelResolver (Helsinki-NLP/opus-mt-*)
 
# ──Translation settings ──────────────────────────────────────────────────────
TRANSLATE_TIMEOUT_SECONDS=10
TRANSLATE_MAX_RETRIES=2
TRANSLATE_RETRY_DELAY_SECONDS=0.5

4. Run the Backend

uvicorn app.main:app --reload

Endpoint	URL
Base API	http://localhost:8000
Swagger UI	http://localhost:8000/docs
ReDoc	http://localhost:8000/redoc
Health	http://localhost:8000/api/v1/health

5. Frontend Setup

cd ../frontend
npm install
npm run dev

Frontend: http://localhost:5173

---

📡 API Reference

All endpoints are prefixed with /api/v1.

POST /api/v1/translate

Translate text between supported languages.

Request body:

{
  "text": "Hello, how are you?",
  "source_lang": "auto",
  "target_lang": "es"
}

Field	Type	Required	Description
text	string	✅	Text to translate (1–500 characters)
source_lang	string	✅	ISO 639-1 code or "auto" for auto-detection
target_lang	string	✅	ISO 639-1 target language code

Response:

{
  "translated_text": "Hola, ¿cómo estás?",
  "source_lang": "en",
  "target_lang": "es"
}

Error codes:

Code	Error	Description
400	unsupported_language	Invalid language code supplied
400	same_language	Source and target languages are identical
429	rate_limit_exceeded	Too many requests — see retry_after in response
502	translation_failed	Service unavailable after all retries
504	translation_timeout	Request exceeded timeout

---

GET /api/v1/languages

Returns all supported language codes.

Response:

{
  "languages": {
    "en": "English",
    "es": "Spanish",
    "fr": "French",
    "de": "German",
    "it": "Italian",
    "pt": "Portuguese",
    "ru": "Russian",
    "ja": "Japanese",
    "ko": "Korean",
    "zh": "Chinese (Simplified)",
    "ar": "Arabic",
    "hi": "Hindi",
    "bn": "Bengali",
    "ta": "Tamil",
    "te": "Telugu"
  },
  "count": 15
}

---

GET /api/v1/health

Health check for uptime monitoring.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-07-06T00:00:00+00:00"
}

---

📁 Project Structure

CodeAlpha_Slango/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   └── routes/
│   │   │       └── translate.py      # /translate, /health, /languages
│   │   ├── core/
│   │   │   ├── config.py             # Pydantic settings (loads .env)
│   │   │   └── logging.py            # Structured logger
│   │   ├── schemas/
│   │   │   └── translation.py        # Request / response models
│   │   ├── services/
│   │   │   ├── base.py               # Abstract TranslatorService
│   │   │   └── google_translate.py   # Google Cloud Translate v2
│   │   ├── utils/
│   │   │   └── rate_limiter.py       # Per-IP in-memory rate limiter
│   │   └── main.py                   # App, middleware, lifespan
│   ├── tests/                        # pytest test suite
│   ├── requirements.txt
│   ├── runtime.txt                   # Pins Python 3.11.9 (for Render)
│   └── .env.example
│
└── frontend/
    ├── src/                          # React components & pages
    ├── public/
    ├── index.html
    ├── vite.config.js
    └── package.json

---

🧪 Testing

cd backend
# With venv active
pytest

# Verbose output
pytest -v

# Specific file
pytest tests/test_translate.py -v

---

🔒 Security

• API credentials are never logged - only metadata (text length, language codes) is recorded
• User input is never stored server-side
• CORS is scoped to explicitly configured origins only
• Per-IP rate limiting guards against abuse

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit your changes using Conventional Commits: git commit -m "feat: add xyz"
4. Push and open a Pull Request

---