elevenlabs addition

README.md

@@ -1,6 +1,219 @@
 # The Translator App
 
-## Run locally
+A Django web application for text translation, with a **separate backend model
+API** (FastAPI) in `backend/` that serves translation engines and model
+inference.
+
+---
+
+## 1. System overview
+
+This repository contains two runtime components:
+
+| Component | Location | Responsibility |
+|---|---|---|
+| Frontend + app logic | `translator_app/` (Django) | UI, form submission, model selection, translation history persistence, cache, and orchestration of translation requests |
+| Model-serving API | `backend/` (FastAPI) | Exposes `/api/translate`, `/api/engines`, `/api/languages`, and routes requests to available providers (NLLB/MADLAD/Ollama/Gemini/Groq) |
+
+High-level request flow:
+
+1. User submits text on Django page (`/`).
+2. Django `translate_api` view validates input and calls `TranslationService`.
+3. `TranslationService` maps app language codes to FLORES-200 codes and calls `MODEL_API_URL`.
+4. FastAPI backend dispatches to the selected provider/engine.
+5. Django stores translation in `TranslationHistory` and returns JSON to the UI.
+
+---
+
+## 2. Repository structure
+
+```text
+.
+├── translator_app/                  # Django app (user-facing application)
+│   ├── translator_project/          # Django project config
+│   ├── translator/                  # App: models, views, services, templates
+│   └── manage.py
+├── backend/                         # FastAPI model-serving API
+│   ├── main.py                      # API entrypoint
+│   ├── providers/                   # Translation engine implementations
+│   ├── languages.py                 # FLORES-200 language map
+│   ├── convert_model.py             # NLLB/MADLAD conversion helper
+│   └── deploy_hf.py                 # Hugging Face Space deployment helper
+├── Dockerfile                       # Root Docker build (backend-focused)
+├── docker-compose.yml               # Local backend compose setup
+└── entrypoint.sh                    # Runtime model conversion + uvicorn start
+```
+
+---
+
+## 3. Django application (`translator_app/`)
+
+### 3.1 Core URLs
+
+- `/` → translation UI (`translator.views.translator`)
+- `/api/translate/` → AJAX translation endpoint (`translator.views.translate_api`)
+- `/history/` → translation history list (`translator.views.history`)
+- `/history/<id>/delete/` → delete one entry
+- `/history/clear/` → clear all entries
+
+### 3.2 Models
+
+Defined in `translator/models.py`:
+
+- `Language`: curated/active language list used by UI when present.
+- `TranslationHistory`: persisted history with source text, translated text,
+  source/target language FK, selected model, and metadata.
+- `TranslationCache`: hash-based cache for repeated translations.
+
+Notable behavior:
+
+- `TranslationHistory.save()` auto-computes `character_count` and `word_count`.
+- History is ordered newest-first and indexed by `(user, -created_at)`.
+
+### 3.3 Views and orchestration
+
+`translator/views.py` coordinates UI + backend translation:
+
+- `_languages()`:
+  - uses DB `Language` rows where `is_active=True`;
+  - falls back to `TranslationService().get_supported_languages()`.
+- `translator()` renders model picker and language selectors.
+- `translate_api()`:
+  - validates JSON payload and limits text to 5000 chars;
+  - validates selected model against `TRANSLATION_MODELS`;
+  - calls `TranslationService.translate(...)`;
+  - persists `TranslationHistory`;
+  - returns translated text + model label.
+
+### 3.4 Service layer
+
+`translator/services/translation_service.py`:
+
+- Detects source language with `langdetect` when source is not provided.
+- Converts app language codes (`en`, `sw`, etc.) to FLORES-200 (`eng_Latn`,
+  `swh_Latn`) for the backend API.
+- Uses cache (`TranslationCache`) keyed by text + source + target + model.
+- Supports:
+  - model API path (via `MODEL_API_URL`), and
+  - optional `deepl_fallback` path when `TRANSLATION_API_KEY` is configured.
+
+### 3.5 Templates/UI behavior
+
+Templates in `translator/templates/translator/`:
+
+- `base.html`: shell layout and Tailwind CDN styling.
+- `translator.html`: main translation page with JS submit flow.
+- `history.html`: persisted history view with delete/clear actions.
+
+Client-side behavior in `translator.html`:
+
+- POSTs JSON to `/api/translate/` with CSRF header.
+- Sends selected `model`, `source_language`, `target_language`, and text.
+- Disables source selector when model is `madlad` (MADLAD auto-detect source).
+
+---
+
+## 4. Backend model API (`backend/`)
+
+### 4.1 API endpoints (`backend/main.py`)
+
+- `GET /api/health` → service status + default available engine.
+- `GET /api/engines` → all engines with metadata and availability.
+- `GET /api/languages` → language list (from FLORES-200 map).
+- `POST /api/translate` → translation endpoint.
+- `GET /scalar` → Scalar API documentation UI.
+
+`/api/translate` request shape:
+
+```json
+{
+  "text": "Hello world",
+  "source": "eng_Latn",
+  "target": "swh_Latn",
+  "engine": "nllb"
+}
+```
+
+Response shape:
+
+```json
+{
+  "translation": "Habari dunia",
+  "source": "eng_Latn",
+  "target": "swh_Latn",
+  "engine": "nllb"
+}
+```
+
+### 4.2 Provider architecture
+
+Providers implement `TranslationProvider` (`backend/providers/base.py`).
+
+Registry in `backend/providers/__init__.py` includes:
+
+- `nllb` (NLLB-200 600M)
+- `nllb_1_3b` (NLLB-200 1.3B)
+- `madlad` (MADLAD-400 3B)
+- `ollama` (local Ollama model)
+- `gemini` (Google API)
+- `groq_qwen` and `groq` (Groq API models)
+
+Availability logic:
+
+- local engines → available when required local model/service exists.
+- API engines → available when server key exists (or key passed by request
+  headers for BYOK flow in FastAPI endpoint).
+
+### 4.3 Language system
+
+`backend/languages.py` provides a full FLORES-200 code map used by local/API
+providers. Django only exposes a curated subset in app-level UI defaults.
+
+### 4.4 Model conversion
+
+`backend/convert_model.py` converts Hugging Face checkpoints to CTranslate2
+int8 models (faster/lower-memory inference). Conversion target path defaults to:
+
+- `models/nllb-200-distilled-600M-int8`
+
+Environment overrides allow converting additional models (e.g. 1.3B, MADLAD).
+
+---
+
+## 5. Configuration
+
+### 5.1 Django (`translator_app/.env`)
+
+Important settings loaded by `translator_project/settings.py`:
+
+- `MODEL_API_URL` (**required** for model API translation path)
+- `TRANSLATION_DEFAULT_MODEL` (default: `nllb`)
+- `TRANSLATION_API_KEY` (optional; enables `deepl_fallback`)
+- `TRANSLATION_API_URL` (optional; DeepL-compatible endpoint override)
+
+Model IDs configured in Django:
+
+- `nllb`
+- `nllb_1_3b`
+- `madlad`
+- `deepl_fallback` (only when fallback key configured)
+
+### 5.2 Backend (`backend/.env`)
+
+See `backend/.env.example` for optional engine keys:
+
+- `GEMINI_API_KEY`
+- `GROQ_API_KEY`
+- `OLLAMA_HOST`, `OLLAMA_MODEL`
+- `CT2_DEVICE`, `CT2_COMPUTE_TYPE`
+- `MADLAD_MODEL_DIR`, related model paths
+- `CORS_ORIGINS`
+
+---
+
+## 6. Local development
+
+### 6.1 Run Django app
 
 ```bash
 cd translator_app
@@ -11,23 +224,78 @@ python manage.py migrate
 python manage.py runserver
 ```
 
-Open http://127.0.0.1:8000/. The translation page has an API-backed submit
-flow, language selectors, model picker, and persisted history at `/history/`.
+App URL: `http://127.0.0.1:8000/`
+
+### 6.2 Run backend API (direct)
+
+```bash
+cd backend
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn main:app --host 0.0.0.0 --port 7860
+```
+
+API URL: `http://127.0.0.1:7860/api/health`
+
+### 6.3 Run backend API via Docker Compose
+
+From repo root:
+
+```bash
+docker compose up --build backend
+```
+
+Compose maps port `7860` and mounts persistent model/cache volumes.
+
+---
+
+## 7. Deployment (Hugging Face Space)
 
-## Configure a provider
+Backend is designed to deploy as a Docker Space (UI stays in Django app).
 
-Create `translator_app/.env` with a Hugging Face token before translating:
+Use helper:
+
+```bash
+HF_TOKEN=hf_your_write_token \
+SPACE_ID=your-hf-user/translator-model-api \
+python backend/deploy_hf.py
+```
+
+Detailed deployment notes are in `backend/HUGGINGFACE_DEPLOYMENT.md`.
+
+After deployment, set Django:
 
 ```env
-HF_TOKEN=hf_your_access_token
-TRANSLATION_DEFAULT_MODEL=nllb_600m
+MODEL_API_URL=https://<your-space>.hf.space/api/translate
 ```
 
-The primary model picker is configured for NLLB-200 600M, NLLB-200 1.3B, and
-MADLAD-400 3B through Hugging Face Inference Providers. NLLB language codes
-are mapped in the service before a request is sent. The selected model is sent
-by the UI and saved with each history item.
+---
+
+## 8. Data and persistence
+
+- Django DB: `translator_app/db.sqlite3`
+- Translation history and cache live in Django DB.
+- Backend model artifacts are stored under configured model directories
+  (often mounted as Docker volumes in local/containerized runs).
+
+---
+
+## 9. Current test coverage
+
+`translator/tests.py` currently covers:
+
+- translation page renders model selector
+- translation API saves history record
+- translation API rejects missing text
+
+---
+
+## 10. Key integration contract (Django ↔ backend)
+
+For end-to-end translation to work:
 
-For an optional DeepL-compatible fallback, additionally set
-`TRANSLATION_API_KEY` (and optionally `TRANSLATION_API_URL`). It will appear in
-the model picker only when configured.
+1. Django `TRANSLATION_MODEL_ENGINES` model IDs must map to backend provider IDs.
+2. Django must map UI language codes to FLORES-200 before calling backend.
+3. `MODEL_API_URL` must point at backend `/api/translate`.
+4. Selected model is persisted in `TranslationHistory.translation_model` and shown in history.

translator_app/translator/services/language_support.py

@@ -0,0 +1,89 @@
+# translator/services/language_support.py
+"""
+Explicit per-model language support.
+
+This is deliberately separate from `TranslationService.NLLB_LANGUAGE_CODES`
+in translation_service.py. That dict answers "does the model API have a wire
+code for this language at all". This file answers a different question:
+"does this specific model actually produce usable output for this language",
+which is what was silently broken.
+
+TWO CONCRETE BUGS THIS FIXES
+-----------------------------
+1. "luo" has no valid FLORES-200 / SALT tag. ISO 639-2 "luo" is a
+   *macrolanguage* umbrella covering Dholuo, Lango, Alur, Adhola and Acholi
+   as distinct languages - it was never a real NLLB/MADLAD language code.
+   That's why translation requests tagged "luo" against nllb / nllb_1_3b /
+   madlad were failing outright: "luo_Latn" doesn't exist on the model's
+   side. If you meant Acholi, that's already covered correctly by "ach".
+   If you specifically need Dholuo/Lango/Alur, none of your current local
+   models support them - only the Google/DeepL fallback paths can.
+
+2. Your language roster (English, Swahili, Luganda, Runyankole, Acholi,
+   Ateso, Lugbara) lines up closely with the Sunbird SALT East African
+   language project rather than any generic multilingual checkpoint. If
+   your deployed HF Space is a SALT-style fine-tune of NLLB, MADLAD-400
+   (a separate, generically-trained Google model) very likely was never
+   fine-tuned on those five Ugandan low-resource languages at all, even
+   though the UI happily offered them for every model.
+
+HOW TO VERIFY / MAINTAIN THIS
+------------------------------
+This table is a best-effort starting point, not a guarantee - I can't see
+your actual deployed HF Space's training data. Two ways to firm it up:
+  a) If your Space exposes a /languages or /health endpoint listing what
+     it was actually fine-tuned/evaluated on, wire `_languages()` in
+     views.py to read it live instead of hardcoding this table.
+  b) Otherwise, test each (model, language) pair once against your Space
+     and adjust the sets below accordingly - a wrong entry here just means
+     a language gets offered when it shouldn't (or hidden when it's fine),
+     not a crash, since translate_api() falls back to Google either way.
+"""
+
+# None = unrestricted (accepts any language pair the frontend can offer).
+MODEL_LANGUAGE_SUPPORT = {
+    "nllb": {"en", "sw", "lg", "nyn", "ach", "teo", "lgg", "rw", "fr", "ar"},
+    "nllb_1_3b": {"en", "sw", "lg", "nyn", "ach", "teo", "lgg", "rw", "fr", "ar"},
+    # Not fine-tuned on the five Ugandan low-resource languages - confirm
+    # against your Space and trim further if it's even narrower than this.
+    "madlad": {"en", "sw", "rw", "fr", "ar"},
+    # DeepL has no coverage at all for sw/lg/nyn/ach/teo/lgg/rw.
+    "deepl_fallback": {"en", "fr", "ar"},
+    "google_fallback": None,
+}
+
+FALLBACK_MODEL = "google_fallback"
+
+# ElevenLabs eleven_multilingual_v2's real language list (per their docs as
+# of mid-2026). None of your East African languages are on it - only en/fr/ar
+# from your roster are. Requests for anything else should never hit the
+# ElevenLabs API; fall back to the browser's speechSynthesis instead.
+ELEVENLABS_MULTILINGUAL_V2_LANGUAGES = {
+    "en", "zh", "es", "hi", "pt", "fr", "de", "ja", "ar", "ko", "id", "it",
+    "nl", "tr", "pl", "sv", "fil", "ms", "ru", "ro", "uk", "el", "cs", "da",
+    "fi", "bg", "hr", "sk", "ta",
+}
+
+
+def supported_codes(model):
+    """Set of codes a model supports, or None if unrestricted."""
+    return MODEL_LANGUAGE_SUPPORT.get(model, set())
+
+
+def model_supports(model, *codes):
+    """True if `model` supports every non-empty code given."""
+    allowed = supported_codes(model)
+    if allowed is None:
+        return True
+    return all(code in allowed for code in codes if code)
+
+
+def resolve_model(requested_model, source_code, target_code):
+    """
+    Return (model_to_use, fell_back). If the requested model can't handle
+    this language pair, silently route to the Google fallback rather than
+    erroring, and tell the caller that happened.
+    """
+    if model_supports(requested_model, source_code, target_code):
+        return requested_model, False
+    return FALLBACK_MODEL, True

translator_app/translator/services/translation_service.py

@@ -87,6 +87,13 @@ class TranslationService:
 
         if model == "deepl_fallback":
             outcome = self._translate_deepl(text, source_language, target_language)
+        elif model == "google_fallback":
+            # Explicit, user-selectable Google fallback. Reuses the exact
+            # same free-fallback call already used internally elsewhere in
+            # this class - no new translation logic introduced.
+            outcome = self._translate_free_fallback(
+                text, source_language, target_language
+            )
         elif model in settings.TRANSLATION_MODEL_ENGINES:
             outcome = self._translate_model_api(
                 text, source_language, target_language, model

translator_app/translator/templates/translator/translator.html

@@ -3,6 +3,8 @@
 <main class="flex-1 w-full max-w-5xl mx-auto px-5 pb-12">
   <form id="translation-form">
     {% csrf_token %}
+    {{ model_language_support_json|json_script:"model-language-support" }}
+    {{ elevenlabs_languages_json|json_script:"elevenlabs-languages" }}
     
     <!-- Header Control Bar -->
     <div class="flex flex-wrap justify-center items-center gap-3 mb-6">
@@ -172,13 +174,62 @@
   const listenResultBtn = document.querySelector('#listen-result');
   const copyBtn = document.querySelector('#copy-result');
 
-  function syncSourceForModel() {
+  // --- Model-aware language filtering ------------------------------------
+  // modelLanguageSupport: { model_code: [lang codes] | null (unrestricted) }
+  const modelLanguageSupport = JSON.parse(document.querySelector('#model-language-support').textContent);
+  const elevenlabsLanguages = new Set(JSON.parse(document.querySelector('#elevenlabs-languages').textContent));
+
+  function supportedSet(model) {
+    const codes = modelLanguageSupport[model];
+    return codes === null || codes === undefined ? null : new Set(codes);
+  }
+
+  // Hide (not remove) options unsupported by the current model, so swapping
+  // models back later doesn't lose the full list. Always keeps "Detect
+  // language" (empty value) visible in the source select.
+  function filterSelectForModel(selectEl, allowed) {
+    let selectedStillValid = false;
+    Array.from(selectEl.options).forEach(opt => {
+      const ok = !opt.value || allowed === null || allowed.has(opt.value);
+      opt.hidden = !ok;
+      opt.disabled = !ok;
+      if (ok && opt.value === selectEl.value) selectedStillValid = true;
+    });
+    if (!selectedStillValid) {
+      const firstOk = Array.from(selectEl.options).find(o => !o.hidden && o.value);
+      if (firstOk) selectEl.value = firstOk.value;
+    }
+  }
+
+  function syncLanguagesForModel() {
     const isMadlad = modelSelect.value === 'madlad';
     sourceSelect.disabled = isMadlad;
     if (isMadlad) sourceSelect.value = '';
+
+    const allowed = supportedSet(modelSelect.value);
+    filterSelectForModel(targetSelect, allowed);
+    if (!isMadlad) filterSelectForModel(sourceSelect, allowed);
+  }
+
+  // If the person picks a language the current model can't handle, hop the
+  // model dropdown to Google fallback automatically rather than letting the
+  // request fail server-side.
+  function ensureModelSupportsSelection() {
+    const allowed = supportedSet(modelSelect.value);
+    if (allowed === null) return;
+    const srcOk = modelSelect.value === 'madlad' || !sourceSelect.value || allowed.has(sourceSelect.value);
+    const tgtOk = !targetSelect.value || allowed.has(targetSelect.value);
+    if (!srcOk || !tgtOk) {
+      modelSelect.value = 'google_fallback';
+      syncLanguagesForModel();
+      message.textContent = 'Switched to Google Translate (fallback) - the previous model doesn\'t support this language.';
+    }
   }
-  modelSelect.addEventListener('change', syncSourceForModel);
-  syncSourceForModel();
+
+  modelSelect.addEventListener('change', syncLanguagesForModel);
+  sourceSelect.addEventListener('change', ensureModelSupportsSelection);
+  targetSelect.addEventListener('change', ensureModelSupportsSelection);
+  syncLanguagesForModel();
 
   function updateSourceControls() {
     count.textContent = `${source.value.length} / 5000 characters`;
@@ -205,7 +256,10 @@
   };
 
   // Text-to-Speech Audio Reader
-  function speakText(text, langCode) {
+  // Tries ElevenLabs first (server-side call, key never touches the
+  // browser); falls back to the browser's built-in speechSynthesis when
+  // ElevenLabs has no voice for the language, or the request fails.
+  function speakWithBrowser(text, langCode) {
     if (!('speechSynthesis' in window) || !text || !text.trim()) return;
     window.speechSynthesis.cancel();
     const utterance = new SpeechSynthesisUtterance(text);
@@ -213,8 +267,55 @@
     window.speechSynthesis.speak(utterance);
   }
 
-  listenSourceBtn.onclick = () => speakText(source.value, sourceSelect.value || 'en');
-  listenResultBtn.onclick = () => speakText(result.textContent, targetSelect.value || 'sw');
+  let currentAudio = null;
+
+  async function speakText(text, langCode, triggerBtn) {
+    if (!text || !text.trim()) return;
+    const lang = (langCode || '').toLowerCase();
+
+    // Skip the network round trip entirely when we already know ElevenLabs
+    // has no voice for this language.
+    if (!lang || !elevenlabsLanguages.has(lang)) {
+      speakWithBrowser(text, lang || 'en');
+      return;
+    }
+
+    const originalLabel = triggerBtn ? triggerBtn.innerHTML : null;
+    if (triggerBtn) {
+      triggerBtn.disabled = true;
+      triggerBtn.innerHTML = '⏳ Loading...';
+    }
+
+    try {
+      const response = await fetch("{% url 'translator:tts_api' %}", {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-CSRFToken': csrf },
+        body: JSON.stringify({ text, language: lang }),
+      });
+
+      if (!response.ok) {
+        // Unsupported language, unconfigured key, or API failure - fall
+        // back quietly rather than surfacing an error for a "Listen" click.
+        speakWithBrowser(text, lang);
+        return;
+      }
+
+      const blob = await response.blob();
+      if (currentAudio) currentAudio.pause();
+      currentAudio = new Audio(URL.createObjectURL(blob));
+      currentAudio.play();
+    } catch (err) {
+      speakWithBrowser(text, lang);
+    } finally {
+      if (triggerBtn) {
+        triggerBtn.disabled = false;
+        triggerBtn.innerHTML = originalLabel;
+      }
+    }
+  }
+
+  listenSourceBtn.onclick = () => speakText(source.value, sourceSelect.value || 'en', listenSourceBtn);
+  listenResultBtn.onclick = () => speakText(result.textContent, targetSelect.value || 'sw', listenResultBtn);
 
   // Speech-to-Text Voice Dictation Assistant
   const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition;
@@ -331,7 +432,12 @@
       if (!response.ok) throw Error(data.error || 'Translation could not be completed.'); 
       
       result.textContent = data.translated_text; 
-      document.querySelector('#result-meta').textContent = `Engine: ${data.model_label || 'Translation'} · Saved to history`; 
+      if (data.model_used && data.model_used !== modelSelect.value) {
+        modelSelect.value = data.model_used;
+        syncLanguagesForModel();
+      }
+      const fallbackNote = data.fell_back_to_google ? ' (auto-switched: selected model doesn\'t support this language pair)' : '';
+      document.querySelector('#result-meta').textContent = `Engine: ${data.model_label || 'Translation'}${fallbackNote} · Saved to history`; 
       copyBtn.classList.remove('hidden');
       copyBtn.classList.add('inline-flex');
       listenResultBtn.classList.remove('hidden');

translator_app/translator/urls.py

@@ -9,6 +9,7 @@ urlpatterns = [
     path('', views.translator, name='translator'),
     path('history/', views.history, name='history'),
     path('api/translate/', views.translate_api, name='translate_api'),
+    path('api/tts/', views.text_to_speech, name='tts_api'),
     path('history/<int:pk>/delete/', views.delete_history, name='delete_history'),
     path('history/clear/', views.clear_history, name='clear_history'),
-]
+]

translator_app/translator/views.py

@@ -1,11 +1,13 @@
 import json
 
+import requests
 from django.conf import settings
-from django.http import JsonResponse
+from django.http import HttpResponse, JsonResponse
 from django.shortcuts import get_object_or_404, redirect, render
 from django.views.decorators.http import require_POST
 
 from .models import Language, TranslationHistory
+from .services import language_support
 from .services.translation_service import TranslationService
 
 
@@ -27,10 +29,16 @@ def _languages():
 
 def translator(request):
     languages = _languages()
+    model_language_support = {
+        model: (sorted(codes) if codes is not None else None)
+        for model, codes in language_support.MODEL_LANGUAGE_SUPPORT.items()
+    }
     return render(request, 'translator/translator.html', {
         'languages': languages,
         'models': settings.TRANSLATION_MODELS,
         'default_model': settings.TRANSLATION_DEFAULT_MODEL,
+        'model_language_support_json': model_language_support,
+        'elevenlabs_languages_json': sorted(language_support.ELEVENLABS_MULTILINGUAL_V2_LANGUAGES),
     })
 
 
@@ -68,6 +76,14 @@ def translate_api(request):
     if model not in allowed_models:
         return JsonResponse({'error': 'Choose a valid translation model.'}, status=400)
 
+    # MADLAD auto-detects and ignores any provided source; skip the source
+    # side of this check for it so we don't fallback unnecessarily.
+    check_source = None if model == 'madlad' else (source_code or None)
+    model, fell_back = language_support.resolve_model(model, check_source, target_code)
+    if model not in allowed_models:
+        # Shouldn't happen (google_fallback is always registered), but stay safe.
+        return JsonResponse({'error': 'No translation model supports this language pair.'}, status=422)
+
     service = TranslationService()
     result = service.translate(text, target_code, source_code or None, model=model)
     if result.get('error'):
@@ -97,9 +113,67 @@ def translate_api(request):
         translation_model=model,
     )
     result['model_label'] = allowed_models[model]
+    result['model_used'] = model
+    result['fell_back_to_google'] = fell_back
     return JsonResponse(result)
 
 
+@require_POST
+def text_to_speech(request):
+    if not settings.ELEVENLABS_API_KEY:
+        return JsonResponse(
+            {'error': 'Text-to-speech is not configured on the server.'}, status=503
+        )
+
+    try:
+        payload = json.loads(request.body)
+    except (TypeError, json.JSONDecodeError):
+        return JsonResponse({'error': 'Send a valid JSON request.'}, status=400)
+
+    text = (payload.get('text') or '').strip()
+    lang = (payload.get('language') or '').lower()
+
+    if not text:
+        return JsonResponse({'error': 'No text to read aloud.'}, status=400)
+    text = text[:5000]
+
+    # Fail fast client-side instead of burning an API call: ElevenLabs'
+    # multilingual model has no voice for these languages yet.
+    if lang and lang not in language_support.ELEVENLABS_MULTILINGUAL_V2_LANGUAGES:
+        return JsonResponse(
+            {
+                'error': 'ElevenLabs does not have a voice for this language yet.',
+                'unsupported_language': True,
+            },
+            status=422,
+        )
+
+    try:
+        response = requests.post(
+            settings.ELEVENLABS_TTS_URL.format(voice_id=settings.ELEVENLABS_VOICE_ID),
+            headers={
+                'xi-api-key': settings.ELEVENLABS_API_KEY,
+                'Content-Type': 'application/json',
+                'Accept': 'audio/mpeg',
+            },
+            json={
+                'text': text,
+                'model_id': settings.ELEVENLABS_MODEL_ID,
+            },
+            timeout=20,
+        )
+    except requests.RequestException:
+        return JsonResponse({'error': 'Speech service is unreachable.'}, status=502)
+
+    if response.status_code != 200:
+        logger_message = response.text[:300] if response.text else ''
+        return JsonResponse(
+            {'error': 'Speech generation failed.', 'detail': logger_message}, status=502
+        )
+
+    return HttpResponse(response.content, content_type='audio/mpeg')
+
+
 @require_POST
 def delete_history(request, pk):
     get_object_or_404(TranslationHistory, pk=pk).delete()

translator_app/translator_project/settings.py

@@ -109,6 +109,7 @@ TRANSLATION_MODELS = (
     ("nllb", "NLLB-200 (600M · Fast)"),
     ("nllb_1_3b", "NLLB-200 (1.3B · Accurate)"),
     ("madlad", "MADLAD-400 (3B · Large)"),
+    ("google_fallback", "Google Translate"),
 )
 TRANSLATION_MODEL_ENGINES = {
     "nllb": "nllb",
@@ -126,3 +127,11 @@ if TRANSLATION_API_KEY:
     TRANSLATION_MODELS += (("deepl_fallback", "DeepL"),)
 # Or for Google Translate:
 # TRANSLATION_API_URL = 'https://translation.googleapis.com/language/translate/v2'
+
+# ElevenLabs text-to-speech. Key must only ever live server-side (env var) -
+# never send it to the browser. Get a key at https://elevenlabs.io/app/settings/api-keys
+# and a voice ID from https://elevenlabs.io/app/voice-library
+ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
+ELEVENLABS_VOICE_ID = os.getenv("ELEVENLABS_VOICE_ID", "21m00Tcm4TlvDq8ikWAM")  # default: "Rachel"
+ELEVENLABS_MODEL_ID = os.getenv("ELEVENLABS_MODEL_ID", "eleven_multilingual_v2")
+ELEVENLABS_TTS_URL = "https://api.elevenlabs.io/v1/text-to-speech/{voice_id}"