Progress

.gitignore

@@ -0,0 +1 @@
+translator_app/.venv

README.md

@@ -1,40 +1,33 @@
-cd translator_app
-
-# Create virtual environment
-python -m venv venv
-
-# Activate virtual environment
-# On Windows:
-venv\Scripts\activate
-# On Mac/Linux:
-source venv/bin/activate
+# The Translator App
 
-# Install required packages
-pip install django djangorestframework requests python-dotenv
+## Run locally
 
-#OR
-pip install -r requirements.txt
-
-#Run Migrations
-python manage.py makemigrations
+```bash
+cd translator_app
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -r ../requirements.txt
 python manage.py migrate
-python manage.py createsuperuser(optional)
+python manage.py runserver
+```
 
-#Install
-pip install libretranslate
+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/`.
 
-#Start Libretranslate 
-#On Windows
-cd translator_app
-venv\Scripts\activate
-libretranslate --host 0.0.0.0 --port 5000
+## Configure a provider
 
-#On Macos
-cd translator_app
-source venv/bin/activate
-libretranslate --host 0.0.0.0 --port 5000
+Create `translator_app/.env` with a Hugging Face token before translating:
 
-#In another terminal
-#Run the Django App
-python manage.py runserver
+```env
+HF_TOKEN=hf_your_access_token
+TRANSLATION_DEFAULT_MODEL=nllb_600m
+```
+
+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.
 
+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.

requirements.txt

@@ -0,0 +1,4 @@
+Django>=5.2
+djangorestframework>=3.15
+python-dotenv>=1.0
+requests>=2.31

translator_app/translator/admin.py

@@ -1,3 +1,23 @@
 from django.contrib import admin
+from .models import Language, TranslationCache, TranslationHistory
 
-# Register your models here.
+
+@admin.register(Language)
+class LanguageAdmin(admin.ModelAdmin):
+    list_display = ('name', 'code', 'native_name', 'is_active')
+    list_filter = ('is_active',)
+    search_fields = ('name', 'native_name', 'code')
+
+
+@admin.register(TranslationHistory)
+class TranslationHistoryAdmin(admin.ModelAdmin):
+    list_display = ('source_text', 'source_language', 'target_language', 'translation_model', 'created_at')
+    list_filter = ('source_language', 'target_language', 'translation_model')
+    search_fields = ('source_text', 'translated_text')
+    readonly_fields = ('character_count', 'word_count', 'created_at')
+
+
+@admin.register(TranslationCache)
+class TranslationCacheAdmin(admin.ModelAdmin):
+    list_display = ('source_text', 'target_language_code', 'access_count', 'last_accessed')
+    search_fields = ('source_text', 'translated_text')

translator_app/translator/migrations/0001_initial.py

@@ -0,0 +1,75 @@
+# Generated by Django 6.0.7 on 2026-07-22 08:44
+
+import django.db.models.deletion
+import django.utils.timezone
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Language',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('code', models.CharField(max_length=10, unique=True)),
+                ('name', models.CharField(max_length=50)),
+                ('native_name', models.CharField(blank=True, max_length=50)),
+                ('is_active', models.BooleanField(default=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                'verbose_name': 'Language',
+                'verbose_name_plural': 'Languages',
+                'ordering': ['name'],
+            },
+        ),
+        migrations.CreateModel(
+            name='TranslationCache',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('source_text_hash', models.CharField(max_length=64, unique=True)),
+                ('source_text', models.TextField()),
+                ('translated_text', models.TextField()),
+                ('source_language_code', models.CharField(max_length=10)),
+                ('target_language_code', models.CharField(max_length=10)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('last_accessed', models.DateTimeField(auto_now=True)),
+                ('access_count', models.IntegerField(default=0)),
+            ],
+            options={
+                'verbose_name': 'Translation Cache',
+                'verbose_name_plural': 'Translation Caches',
+                'indexes': [models.Index(fields=['source_text_hash', 'target_language_code'], name='translator__source__c37921_idx')],
+            },
+        ),
+        migrations.CreateModel(
+            name='TranslationHistory',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('source_text', models.TextField()),
+                ('translated_text', models.TextField()),
+                ('detected_source_language', models.CharField(blank=True, max_length=10)),
+                ('character_count', models.IntegerField(default=0)),
+                ('word_count', models.IntegerField(default=0)),
+                ('created_at', models.DateTimeField(default=django.utils.timezone.now)),
+                ('source_language', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='source_translations', to='translator.language')),
+                ('target_language', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='target_translations', to='translator.language')),
+                ('user', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='translations', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'Translation History',
+                'verbose_name_plural': 'Translation Histories',
+                'ordering': ['-created_at'],
+                'indexes': [models.Index(fields=['user', '-created_at'], name='translator__user_id_18b742_idx')],
+            },
+        ),
+    ]

translator_app/translator/migrations/0002_translationhistory_translation_model.py

@@ -0,0 +1,15 @@
+# Generated by Django 6.0.7 on 2026-07-22
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [('translator', '0001_initial')]
+
+    operations = [
+        migrations.AddField(
+            model_name='translationhistory',
+            name='translation_model',
+            field=models.CharField(blank=True, max_length=100),
+        ),
+    ]

translator_app/translator/models.py

@@ -45,6 +45,7 @@ class TranslationHistory(models.Model):
         related_name='target_translations'
     )
     detected_source_language = models.CharField(max_length=10, blank=True)
+    translation_model = models.CharField(max_length=100, blank=True)
     character_count = models.IntegerField(default=0)
     word_count = models.IntegerField(default=0)
     created_at = models.DateTimeField(default=timezone.now)
@@ -87,4 +88,4 @@ class TranslationCache(models.Model):
         ]
 
     def __str__(self):
-        return f"{self.source_text[:50]}... -> {self.target_language_code}"
+        return f"{self.source_text[:50]}... -> {self.target_language_code}"

translator_app/translator/services/translation_service.py

@@ -1,224 +1,161 @@
-# translator/services/translation_service.py
+"""Translation providers behind one stable application-level contract."""
 
 import hashlib
-import json
 import logging
+
 import requests
 from django.conf import settings
-from django.core.cache import cache
 from django.utils import timezone
+
 from ..models import TranslationCache
 
 logger = logging.getLogger(__name__)
 
+
 class TranslationService:
-    """Service class for handling translation operations"""
-    
+    """Run the selected ML model, with an optional DeepL-compatible fallback."""
+
+    # NLLB requires its FLORES language tags. MADLAD accepts ISO language codes.
+    NLLB_LANGUAGE_CODES = {
+        'en': 'eng_Latn', 'es': 'spa_Latn', 'fr': 'fra_Latn', 'de': 'deu_Latn',
+        'it': 'ita_Latn', 'pt': 'por_Latn', 'ru': 'rus_Cyrl', 'zh': 'zho_Hans',
+        'ja': 'jpn_Jpan', 'ko': 'kor_Hang', 'ar': 'arb_Arab', 'hi': 'hin_Deva',
+        'sw': 'swh_Latn', 'yo': 'yor_Latn', 'ha': 'hau_Latn', 'ig': 'ibo_Latn',
+    }
+
     def __init__(self):
-        self.api_key = settings.TRANSLATION_API_KEY
-        self.api_url = settings.TRANSLATION_API_URL
         self.supported_languages = self._get_supported_languages()
-    
+
     def _get_supported_languages(self):
-        """Get list of supported languages"""
-        # Language codes mapping
         return {
-            'en': 'English',
-            'es': 'Spanish',
-            'fr': 'French',
-            'de': 'German',
-            'it': 'Italian',
-            'pt': 'Portuguese',
-            'ru': 'Russian',
-            'zh': 'Chinese',
-            'ja': 'Japanese',
-            'ko': 'Korean',
-            'ar': 'Arabic',
-            'hi': 'Hindi',
-            'sw': 'Swahili',  # Kenyan languages
-            'yo': 'Yoruba',
-            'ha': 'Hausa',
-            'ig': 'Igbo',
+            'en': 'English', 'es': 'Spanish', 'fr': 'French', 'de': 'German',
+            'it': 'Italian', 'pt': 'Portuguese', 'ru': 'Russian', 'zh': 'Chinese',
+            'ja': 'Japanese', 'ko': 'Korean', 'ar': 'Arabic', 'hi': 'Hindi',
+            'sw': 'Swahili', 'yo': 'Yoruba', 'ha': 'Hausa', 'ig': 'Igbo',
         }
-    
+
     def get_supported_languages(self):
-        """Return supported languages as a list of dicts"""
         return [{'code': code, 'name': name} for code, name in self.supported_languages.items()]
-    
+
     def detect_language(self, text):
-        """Detect the language of the input text"""
-        if not text or len(text.strip()) < 2:
-            return {'code': 'en', 'name': 'English', 'confidence': 1.0}
-        
-        try:
-            # For DeepL API
-            response = requests.post(
-                f"{self.api_url}/document",
-                headers={
-                    'Authorization': f'DeepL-Auth-Key {self.api_key}',
-                    'Content-Type': 'application/json'
-                },
-                json={'text': [text]},
-                timeout=10
-            )
-            
-            if response.status_code == 200:
-                data = response.json()
-                if data.get('detections'):
-                    detection = data['detections'][0]
-                    if detection:
-                        return {
-                            'code': detection.get('language', 'en'),
-                            'name': self.supported_languages.get(detection.get('language', 'en'), 'Unknown'),
-                            'confidence': detection.get('confidence', 0.0)
-                        }
-            
-            # Fallback: Use Google Translate API
-            # response = requests.post(...)
-            
-            # If API fails, use a simple detection approach
-            # (Use langdetect library for better detection)
-            return self._simple_detect(text)
-            
-        except Exception as e:
-            logger.error(f"Language detection failed: {str(e)}")
-            return self._simple_detect(text)
-    
-    def _simple_detect(self, text):
-        """Simple language detection fallback"""
-        # This is a very basic approach - use langdetect library in production
-        # For now, assume English if text has mostly ASCII characters
-        if all(ord(c) < 128 for c in text):
-            return {'code': 'en', 'name': 'English', 'confidence': 0.6}
-        else:
-            # Could add more heuristics here
-            return {'code': 'en', 'name': 'English', 'confidence': 0.6}
-    
-    def translate(self, text, target_language, source_language=None):
-        """Translate text from source to target language"""
+        # Deliberately local and deterministic until the ML team supplies a detector.
+        code = 'en' if all(ord(char) < 128 for char in text) else 'en'
+        return {'code': code, 'name': self.supported_languages[code], 'confidence': 0.6}
+
+    def translate(self, text, target_language, source_language=None, model=None):
         if not text or not text.strip():
             return {'error': 'Text cannot be empty'}
-        
-        # Generate cache key
-        cache_key = self._generate_cache_key(text, source_language, target_language)
-        
-        # Check cache
-        cached_result = self._get_from_cache(cache_key)
-        if cached_result:
-            return cached_result
-        
+
+        model = model or settings.TRANSLATION_DEFAULT_MODEL
+        source_language = source_language or self.detect_language(text)['code']
+        cache_key = self._generate_cache_key(text, source_language, target_language, model)
+        cached = self._get_from_cache(cache_key)
+        if cached:
+            cached['model'] = model
+            return cached
+
+        if model == 'deepl_fallback':
+            outcome = self._translate_deepl(text, source_language, target_language)
+        elif model in settings.TRANSLATION_MODEL_IDS:
+            outcome = self._translate_hugging_face(text, source_language, target_language, model)
+        else:
+            return {'error': 'The selected translation model is unavailable.'}
+
+        if outcome.get('error'):
+            return outcome
+
+        translated_text = outcome['translated_text']
+        self._save_to_cache(cache_key, text, translated_text, source_language, target_language)
+        return {
+            'source_text': text,
+            'translated_text': translated_text,
+            'source_language': source_language,
+            'target_language': target_language,
+            'model': model,
+        }
+
+    def _translate_hugging_face(self, text, source_language, target_language, model):
+        if not settings.HF_TOKEN:
+            return {'error': 'ML translation is not configured. Add HF_TOKEN to your environment.'}
+
+        model_id = settings.TRANSLATION_MODEL_IDS[model]
+        if model.startswith('nllb_'):
+            try:
+                source = self.NLLB_LANGUAGE_CODES[source_language]
+                target = self.NLLB_LANGUAGE_CODES[target_language]
+            except KeyError:
+                return {'error': 'The selected NLLB model does not support one of these languages.'}
+        else:
+            source, target = source_language, target_language
+
         try:
-            # Prepare translation request
-            response = self._call_translation_api(text, target_language, source_language)
-            
-            if response.status_code == 200:
-                translated_text = self._parse_translation_response(response.json())
-                
-                # Cache the result
-                self._save_to_cache(cache_key, text, translated_text, source_language, target_language)
-                
-                return {
-                    'source_text': text,
-                    'translated_text': translated_text,
-                    'source_language': source_language or 'auto-detected',
-                    'target_language': target_language
-                }
-            else:
-                logger.error(f"Translation API error: {response.status_code} - {response.text}")
-                return {
-                    'error': f'Translation failed with status code: {response.status_code}',
-                    'details': response.text
-                }
-                
+            response = requests.post(
+                settings.HF_INFERENCE_URL.format(model_id=model_id),
+                headers={'Authorization': f'Bearer {settings.HF_TOKEN}'},
+                json={'inputs': text, 'parameters': {'src_lang': source, 'tgt_lang': target}},
+                timeout=60,
+            )
+            if response.status_code != 200:
+                logger.warning('Hugging Face translation failed: %s %s', response.status_code, response.text)
+                return {'error': 'The ML translation service could not complete this request.'}
+            translated_text = response.json().get('translation_text')
+            if not translated_text:
+                return {'error': 'The ML model returned no translation.'}
+            return {'translated_text': translated_text}
         except requests.exceptions.Timeout:
-            return {'error': 'Translation request timed out'}
+            return {'error': 'The ML translation request timed out.'}
         except requests.exceptions.ConnectionError:
-            return {'error': 'Failed to connect to translation service'}
-        except Exception as e:
-            logger.error(f"Translation error: {str(e)}")
-            return {'error': f'Translation failed: {str(e)}'}
-    
-    def _call_translation_api(self, text, target_language, source_language=None):
-        """Make the API call to the translation service"""
-        # Using DeepL API as example
-        headers = {
-            'Authorization': f'DeepL-Auth-Key {self.api_key}',
-            'Content-Type': 'application/json'
-        }
-        
-        payload = {
-            'text': [text],
-            'target_lang': target_language.upper()
-        }
-        
-        if source_language and source_language != 'auto':
-            payload['source_lang'] = source_language.upper()
-        
-        response = requests.post(
-            self.api_url,
-            headers=headers,
-            json=payload,
-            timeout=30
-        )
-        
-        return response
-    
-    def _parse_translation_response(self, response_data):
-        """Parse the translation API response"""
+            return {'error': 'Could not connect to the ML translation service.'}
+        except (ValueError, requests.RequestException) as error:
+            logger.exception('ML translation failed: %s', error)
+            return {'error': 'The ML translation service returned an invalid response.'}
+
+    def _translate_deepl(self, text, source_language, target_language):
+        if not settings.TRANSLATION_API_KEY:
+            return {'error': 'Traditional fallback is not configured.'}
         try:
-            # DeepL response format
-            if 'translations' in response_data and response_data['translations']:
-                return response_data['translations'][0].get('text', '')
-            
-            # Google Translate response format (alternative)
-            if 'data' in response_data and 'translations' in response_data['data']:
-                return response_data['data']['translations'][0].get('translatedText', '')
-            
-            return 'Translation not available'
-        except (KeyError, IndexError, TypeError) as e:
-            logger.error(f"Failed to parse translation response: {str(e)}")
-            return 'Translation parsing failed'
-    
-    def _generate_cache_key(self, text, source_language, target_language):
-        """Generate a unique cache key for a translation"""
-        content = f"{text}|{source_language or 'auto'}|{target_language}"
+            response = requests.post(
+                settings.TRANSLATION_API_URL,
+                headers={'Authorization': f'DeepL-Auth-Key {settings.TRANSLATION_API_KEY}'},
+                json={'text': [text], 'source_lang': source_language.upper(), 'target_lang': target_language.upper()},
+                timeout=30,
+            )
+            if response.status_code != 200:
+                return {'error': 'The fallback translation service could not complete this request.'}
+            translated_text = response.json()['translations'][0]['text']
+            return {'translated_text': translated_text}
+        except (KeyError, IndexError, ValueError, requests.RequestException) as error:
+            logger.exception('Fallback translation failed: %s', error)
+            return {'error': 'The fallback translation service returned an invalid response.'}
+
+    @staticmethod
+    def _generate_cache_key(text, source_language, target_language, model):
+        content = f'{text}|{source_language}|{target_language}|{model}'
         return hashlib.sha256(content.encode('utf-8')).hexdigest()
-    
-    def _get_from_cache(self, cache_key):
-        """Get translation from cache"""
+
+    @staticmethod
+    def _get_from_cache(cache_key):
         try:
-            cache_entry = TranslationCache.objects.filter(
-                source_text_hash=cache_key
-            ).first()
-            
-            if cache_entry:
-                cache_entry.access_count += 1
-                cache_entry.last_accessed = timezone.now()
-                cache_entry.save()
-                
-                return {
-                    'source_text': cache_entry.source_text,
-                    'translated_text': cache_entry.translated_text,
-                    'source_language': cache_entry.source_language_code,
-                    'target_language': cache_entry.target_language_code,
-                    'from_cache': True
-                }
+            entry = TranslationCache.objects.filter(source_text_hash=cache_key).first()
+            if not entry:
+                return None
+            entry.access_count += 1
+            entry.last_accessed = timezone.now()
+            entry.save(update_fields=['access_count', 'last_accessed'])
+            return {'source_text': entry.source_text, 'translated_text': entry.translated_text,
+                    'source_language': entry.source_language_code, 'target_language': entry.target_language_code,
+                    'from_cache': True}
+        except Exception:
+            logger.exception('Translation cache lookup failed')
             return None
-        except Exception as e:
-            logger.error(f"Cache retrieval failed: {str(e)}")
-            return None
-    
-    def _save_to_cache(self, cache_key, source_text, translated_text, source_language, target_language):
-        """Save translation to cache"""
+
+    @staticmethod
+    def _save_to_cache(cache_key, source_text, translated_text, source_language, target_language):
         try:
             TranslationCache.objects.update_or_create(
                 source_text_hash=cache_key,
-                defaults={
-                    'source_text': source_text,
-                    'translated_text': translated_text,
-                    'source_language_code': source_language or 'auto',
-                    'target_language_code': target_language
-                }
+                defaults={'source_text': source_text, 'translated_text': translated_text,
+                          'source_language_code': source_language, 'target_language_code': target_language},
             )
-        except Exception as e:
-            logger.error(f"Cache save failed: {str(e)}")
+        except Exception:
+            logger.exception('Translation cache save failed')

translator_app/translator/templates/translator/base.html

@@ -0,0 +1,21 @@
+{% load static %}
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{% block title %}The Translator App{% endblock %}</title>
+  <script src="https://cdn.tailwindcss.com?plugins=forms"></script>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@500;600;700;800&family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <script>tailwind.config={theme:{extend:{colors:{primary:'#84532e',ink:'#22303a',cream:'#fffaf6',sand:'#ffbe91',mist:'#f3e9e1'},fontFamily:{display:['Bricolage Grotesque'],body:['Plus Jakarta Sans']}}}}</script>
+  <style>body{background:#fffaf6}.quiet-loading:after{content:'';position:absolute;bottom:0;left:0;width:100%;height:2px;background:linear-gradient(90deg,transparent,#84532e,transparent);animation:load 1.4s infinite}@keyframes load{from{transform:translateX(-100%)}to{transform:translateX(100%)}}</style>
+  {% block extra_head %}{% endblock %}
+</head>
+<body class="min-h-screen font-body text-ink flex flex-col">
+  <header class="w-full max-w-6xl mx-auto px-5 pt-9 pb-7 text-center">
+    <a href="{% url 'translator:translator' %}" class="font-display text-3xl md:text-5xl font-extrabold tracking-tight text-primary">The Translator App</a>
+  </header>
+  {% block content %}{% endblock %}
+  <footer class="py-10 text-center text-sm text-stone-500"><p>© {% now 'Y' %} The Translator App</p></footer>
+</body>
+</html>

translator_app/translator/templates/translator/history.html

@@ -0,0 +1,9 @@
+{% extends 'translator/base.html' %}
+{% block title %}History · The Translator App{% endblock %}
+{% block content %}
+<main class="flex-1 w-full max-w-3xl mx-auto px-5 pb-12">
+  <div class="mb-7 flex items-center justify-between"><h1 class="font-display text-3xl font-bold text-primary">History</h1>{% if translations %}<form method="post" action="{% url 'translator:clear_history' %}">{% csrf_token %}<button class="text-sm font-bold text-red-700 hover:underline">Clear all</button></form>{% endif %}</div>
+  <div class="space-y-4">{% for item in translations %}<article class="group rounded-xl border border-stone-100 bg-white p-5 shadow-sm"><div class="mb-3 flex justify-between gap-4 text-xs font-bold uppercase tracking-wider text-stone-400"><span>{{ item.source_language.name|default:item.detected_source_language|default:'Detected' }} → {{ item.target_language.name|default:'Unknown' }}</span><time>{{ item.created_at|timesince }} ago</time></div><p class="text-stone-700">{{ item.source_text }}</p><p class="mt-2 font-medium italic text-primary">{{ item.translated_text }}</p><div class="mt-3 flex items-center justify-between"><span class="text-xs text-stone-400">{{ item.model_label|default:'Translation' }}</span><form method="post" action="{% url 'translator:delete_history' item.pk %}">{% csrf_token %}<button class="text-xs font-bold text-stone-400 hover:text-red-700">Delete</button></form></div></article>{% empty %}<div class="rounded-xl border border-dashed border-stone-300 p-12 text-center text-stone-500">No translations yet. <a class="font-bold text-primary underline" href="{% url 'translator:translator' %}">Start translating</a>.</div>{% endfor %}</div>
+  <div class="mt-10 text-center"><a class="rounded-full bg-primary px-6 py-3 text-sm font-bold text-white" href="{% url 'translator:translator' %}">Back to translate</a></div>
+</main>
+{% endblock %}

translator_app/translator/templates/translator/translator.html

@@ -0,0 +1,47 @@
+{% extends 'translator/base.html' %}
+{% block content %}
+<main class="flex-1 w-full max-w-5xl mx-auto px-5 pb-12">
+  <form id="translation-form">
+    {% csrf_token %}
+    <div class="flex flex-wrap justify-center items-center gap-3 mb-5">
+      <select id="source-language" aria-label="Source language" class="rounded-full border-stone-200 bg-white px-5 py-2.5 text-sm font-semibold text-primary shadow-sm focus:border-primary focus:ring-primary">
+        <option value="">Detect language</option>{% for language in languages %}<option value="{{ language.code }}"{% if language.code == 'en' %} selected{% endif %}>{{ language.name }}</option>{% endfor %}
+      </select>
+      <button id="swap-languages" type="button" title="Swap languages" class="rounded-full bg-sand px-3 py-2.5 text-primary transition hover:rotate-180">⇄</button>
+      <select id="target-language" aria-label="Target language" class="rounded-full border-stone-200 bg-white px-5 py-2.5 text-sm font-semibold text-primary shadow-sm focus:border-primary focus:ring-primary">
+        {% for language in languages %}<option value="{{ language.code }}"{% if language.code == 'sw' %} selected{% endif %}>{{ language.name }}</option>{% endfor %}
+      </select>
+      <label class="flex items-center gap-2 rounded-full border border-stone-200 bg-white px-4 py-2 text-sm font-semibold text-stone-600 shadow-sm">Model
+        <select id="translation-model" aria-label="Translation model" class="border-0 bg-transparent py-0 pl-1 pr-7 text-primary focus:ring-0">
+          {% for value, label in models %}<option value="{{ value }}"{% if value == default_model %} selected{% endif %}>{{ label }}</option>{% endfor %}
+        </select>
+      </label>
+    </div>
+    <div class="rounded-2xl border border-stone-200 bg-white p-5 md:p-7 shadow-xl shadow-stone-200/40 md:flex md:gap-7">
+      <section class="flex min-h-72 flex-1 flex-col">
+        <label for="source-text" class="mb-3 text-xs font-bold uppercase tracking-widest text-stone-400">Source</label>
+        <textarea id="source-text" maxlength="5000" class="min-h-52 w-full flex-1 resize-none border-0 p-0 font-display text-2xl leading-relaxed text-primary placeholder:text-stone-300 focus:ring-0" placeholder="Enter text to translate..."></textarea>
+        <div class="mt-3 flex justify-between border-t border-stone-100 pt-3 text-xs text-stone-400"><button id="clear-source" type="button" class="font-semibold text-primary hover:underline">Clear</button><span id="character-count">0 / 5000 characters</span></div>
+      </section>
+      <div class="my-5 hidden w-px bg-stone-100 md:block"></div>
+      <section class="relative flex min-h-72 flex-1 flex-col">
+        <div class="mb-3 flex items-center justify-between"><span class="text-xs font-bold uppercase tracking-widest text-stone-400">Translation</span><button id="copy-result" type="button" class="hidden rounded-full px-3 py-1 text-xs font-bold text-primary hover:bg-mist">Copy</button></div>
+        <p id="translated-text" aria-live="polite" class="relative flex-1 whitespace-pre-wrap font-display text-2xl leading-relaxed text-primary"><span class="text-stone-300">Your translation will appear here.</span></p>
+        <p id="result-meta" class="mt-3 text-xs text-stone-400"></p>
+      </section>
+    </div>
+    <div class="mt-6 flex flex-col items-center gap-3"><button id="translate-button" class="rounded-full bg-primary px-10 py-4 font-display text-lg font-bold uppercase tracking-wider text-white shadow-lg shadow-primary/30 transition hover:scale-105 disabled:cursor-wait disabled:opacity-70">Translate</button><p id="form-message" role="alert" class="min-h-5 text-sm text-red-700"></p></div>
+  </form>
+  <div class="mt-12 text-center"><a href="{% url 'translator:history' %}" class="text-sm font-bold text-primary underline underline-offset-4 hover:text-stone-700">View history</a></div>
+</main>
+<script>
+const form=document.querySelector('#translation-form'), source=document.querySelector('#source-text'), result=document.querySelector('#translated-text'), message=document.querySelector('#form-message'), button=document.querySelector('#translate-button'), count=document.querySelector('#character-count');
+const csrf=document.querySelector('[name=csrfmiddlewaretoken]').value;
+source.addEventListener('input',()=>count.textContent=`${source.value.length} / 5000 characters`);
+document.querySelector('#clear-source').onclick=()=>{source.value='';source.dispatchEvent(new Event('input'));source.focus()};
+document.querySelector('#swap-languages').onclick=()=>{const a=document.querySelector('#source-language'),b=document.querySelector('#target-language');if(a.value){[a.value,b.value]=[b.value,a.value]}};
+document.querySelector('#copy-result').onclick=async()=>{await navigator.clipboard.writeText(result.textContent);document.querySelector('#copy-result').textContent='Copied';setTimeout(()=>document.querySelector('#copy-result').textContent='Copy',1200)};
+form.addEventListener('submit',async e=>{e.preventDefault();message.textContent='';button.disabled=true;button.textContent='Translating…';result.classList.add('quiet-loading');
+  try {const response=await fetch("{% url 'translator:translate_api' %}",{method:'POST',headers:{'Content-Type':'application/json','X-CSRFToken':csrf},body:JSON.stringify({text:source.value,source_language:document.querySelector('#source-language').value,target_language:document.querySelector('#target-language').value,model:document.querySelector('#translation-model').value})});const data=await response.json();if(!response.ok)throw Error(data.error||'Translation could not be completed.');result.textContent=data.translated_text;document.querySelector('#result-meta').textContent=`${data.model_label||'Translation'} · saved to history`;document.querySelector('#copy-result').classList.remove('hidden')}catch(error){message.textContent=error.message;result.innerHTML='<span class="text-stone-300">Your translation will appear here.</span>'}finally{button.disabled=false;button.textContent='Translate';result.classList.remove('quiet-loading')}});
+</script>
+{% endblock %}

translator_app/translator/tests.py

@@ -1,3 +1,35 @@
 from django.test import TestCase
+from unittest.mock import patch
 
-# Create your tests here.
+from django.urls import reverse
+
+from .models import TranslationHistory
+
+class TranslatorViewsTests(TestCase):
+    def test_translator_page_renders_model_picker(self):
+        response = self.client.get(reverse('translator:translator'))
+        self.assertContains(response, 'Translation model')
+        self.assertContains(response, 'NLLB-200 (600M')
+
+    @patch('translator.views.TranslationService.translate')
+    def test_translation_api_saves_history(self, translate):
+        translate.return_value = {
+            'source_text': 'Hello', 'translated_text': 'Jambo',
+            'source_language': 'en', 'target_language': 'sw', 'model': 'nllb_600m',
+        }
+        response = self.client.post(
+            reverse('translator:translate_api'),
+            data='{"text":"Hello","source_language":"en","target_language":"sw","model":"nllb_600m"}',
+            content_type='application/json',
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()['translated_text'], 'Jambo')
+        history = TranslationHistory.objects.get()
+        self.assertEqual(history.translation_model, 'nllb_600m')
+        self.assertEqual(history.source_text, 'Hello')
+
+    def test_translation_api_rejects_missing_text(self):
+        response = self.client.post(
+            reverse('translator:translate_api'), data='{}', content_type='application/json'
+        )
+        self.assertEqual(response.status_code, 400)

translator_app/translator/urls.py

@@ -0,0 +1,14 @@
+from django.urls import path
+
+from . import views
+
+
+app_name = 'translator'
+
+urlpatterns = [
+    path('', views.translator, name='translator'),
+    path('history/', views.history, name='history'),
+    path('api/translate/', views.translate_api, name='translate_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

@@ -0,0 +1,102 @@
+import json
+
+from django.conf import settings
+from django.http import 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.translation_service import TranslationService
+
+
+def _languages():
+    """Use database languages when curated, otherwise use provider defaults."""
+    saved = Language.objects.filter(is_active=True).values('code', 'name')
+    return list(saved) or TranslationService().get_supported_languages()
+
+
+def translator(request):
+    languages = _languages()
+    return render(request, 'translator/translator.html', {
+        'languages': languages,
+        'models': settings.TRANSLATION_MODELS,
+        'default_model': settings.TRANSLATION_DEFAULT_MODEL,
+    })
+
+
+def history(request):
+    translations = TranslationHistory.objects.select_related(
+        'source_language', 'target_language'
+    )[:100]
+    model_labels = dict(settings.TRANSLATION_MODELS)
+    for item in translations:
+        item.model_label = model_labels.get(item.translation_model, item.translation_model)
+    return render(request, 'translator/history.html', {
+        'translations': translations,
+    })
+
+
+@require_POST
+def translate_api(request):
+    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()
+    source_code = (payload.get('source_language') or '').lower()
+    target_code = (payload.get('target_language') or '').lower()
+    model = payload.get('model') or settings.TRANSLATION_DEFAULT_MODEL
+    allowed_models = dict(settings.TRANSLATION_MODELS)
+
+    if not text:
+        return JsonResponse({'error': 'Enter text to translate.'}, status=400)
+    if len(text) > 5000:
+        return JsonResponse({'error': 'Text is limited to 5,000 characters.'}, status=400)
+    if not target_code:
+        return JsonResponse({'error': 'Choose a target language.'}, status=400)
+    if model not in allowed_models:
+        return JsonResponse({'error': 'Choose a valid translation model.'}, status=400)
+
+    service = TranslationService()
+    result = service.translate(text, target_code, source_code or None, model=model)
+    if result.get('error'):
+        return JsonResponse(result, status=502)
+
+    source_code = result.get('source_language', source_code)
+    known_languages = {item['code']: item['name'] for item in service.get_supported_languages()}
+
+    def language_for(code):
+        if not code or code == 'auto-detected':
+            return None
+        language, _ = Language.objects.get_or_create(
+            code=code,
+            defaults={'name': known_languages.get(code, code.upper())},
+        )
+        return language
+
+    source_language = language_for(source_code)
+    target_language = language_for(target_code)
+    TranslationHistory.objects.create(
+        user=request.user if request.user.is_authenticated else None,
+        source_text=text,
+        translated_text=result['translated_text'],
+        source_language=source_language,
+        target_language=target_language,
+        detected_source_language=source_code if source_code != 'auto-detected' else '',
+        translation_model=model,
+    )
+    result['model_label'] = allowed_models[model]
+    return JsonResponse(result)
+
+
+@require_POST
+def delete_history(request, pk):
+    get_object_or_404(TranslationHistory, pk=pk).delete()
+    return redirect('translator:history')
+
+
+@require_POST
+def clear_history(request):
+    TranslationHistory.objects.all().delete()
+    return redirect('translator:history')

translator_app/translator_project/settings.py

@@ -8,98 +8,120 @@ load_dotenv()
 
 BASE_DIR = Path(__file__).resolve().parent.parent
 
-SECRET_KEY = os.getenv('DJANGO_SECRET_KEY', 'your-secret-key-here')
+SECRET_KEY = os.getenv("DJANGO_SECRET_KEY", "your-secret-key-here")
 
 DEBUG = True
 
-ALLOWED_HOSTS = ['localhost', '127.0.0.1']
+ALLOWED_HOSTS = ["localhost", "127.0.0.1"]
 
 # Application definition
 INSTALLED_APPS = [
-    'django.contrib.admin',
-    'django.contrib.auth',
-    'django.contrib.contenttypes',
-    'django.contrib.sessions',
-    'django.contrib.messages',
-    'django.contrib.staticfiles',
-    'rest_framework',
-    'translator',  # Our app
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    "rest_framework",
+    "translator",  # Our app
 ]
 
 MIDDLEWARE = [
-    'django.middleware.security.SecurityMiddleware',
-    'django.contrib.sessions.middleware.SessionMiddleware',
-    'django.middleware.common.CommonMiddleware',
-    'django.middleware.csrf.CsrfViewMiddleware',
-    'django.contrib.auth.middleware.AuthenticationMiddleware',
-    'django.contrib.messages.middleware.MessageMiddleware',
-    'django.middleware.clickjacking.XFrameOptionsMiddleware',
+    "django.middleware.security.SecurityMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+    "django.middleware.clickjacking.XFrameOptionsMiddleware",
 ]
 
-ROOT_URLCONF = 'translator_project.urls'
+ROOT_URLCONF = "translator_project.urls"
 
 TEMPLATES = [
     {
-        'BACKEND': 'django.template.backends.django.DjangoTemplates',
-        'DIRS': [],
-        'APP_DIRS': True,
-        'OPTIONS': {
-            'context_processors': [
-                'django.template.context_processors.debug',
-                'django.template.context_processors.request',
-                'django.contrib.auth.context_processors.auth',
-                'django.contrib.messages.context_processors.messages',
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.debug",
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
             ],
         },
     },
 ]
 
-WSGI_APPLICATION = 'translator_project.wsgi.application'
+WSGI_APPLICATION = "translator_project.wsgi.application"
 
 # Database
 DATABASES = {
-    'default': {
-        'ENGINE': 'django.db.backends.sqlite3',
-        'NAME': BASE_DIR / 'db.sqlite3',
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": BASE_DIR / "db.sqlite3",
     }
 }
 
 # Password validation
 AUTH_PASSWORD_VALIDATORS = [
     {
-        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
+        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
     },
     {
-        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
+        "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
     },
     {
-        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
+        "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
     },
     {
-        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
+        "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
     },
 ]
 
 # Internationalization
-LANGUAGE_CODE = 'en-us'
-TIME_ZONE = 'UTC'
+LANGUAGE_CODE = "en-us"
+TIME_ZONE = "UTC"
 USE_I18N = True
 USE_TZ = True
 
 # Static files
-STATIC_URL = 'static/'
-STATICFILES_DIRS = [os.path.join(BASE_DIR, 'static')]
-STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
+STATIC_URL = "static/"
+# STATICFILES_DIRS = [os.path.join(BASE_DIR, 'static')]
+STATIC_ROOT = os.path.join(BASE_DIR, "staticfiles")
 
 # Media files
-MEDIA_URL = '/media/'
-MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
+MEDIA_URL = "/media/"
+MEDIA_ROOT = os.path.join(BASE_DIR, "media")
 
 # Default primary key field type
-DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+
+# ML translation settings. Keep secrets in translator_app/.env, never in source.
+HF_TOKEN = os.getenv("HF_TOKEN")
+HF_INFERENCE_URL = os.getenv(
+    "HF_INFERENCE_URL", "https://router.huggingface.co/hf-inference/models/{model_id}"
+)
+TRANSLATION_DEFAULT_MODEL = os.getenv("TRANSLATION_DEFAULT_MODEL", "nllb_600m")
+TRANSLATION_MODELS = (
+    ("nllb_600m", "NLLB-200 (600M · Fast)"),
+    ("nllb_1.3b", "NLLB-200 (1.3B · Accurate)"),
+    ("madlad_3b", "MADLAD-400 (3B · Large)"),
+)
+TRANSLATION_MODEL_IDS = {
+    "nllb_600m": "facebook/nllb-200-distilled-600M",
+    "nllb_1.3b": "facebook/nllb-200-distilled-1.3B",
+    "madlad_3b": "google/madlad-400-3b-mt",
+}
 
-# Translation API settings
-TRANSLATION_API_KEY = os.getenv('TRANSLATION_API_KEY')
-TRANSLATION_API_URL = os.getenv('TRANSLATION_API_URL', 'https://api-free.deepl.com/v2/translate')
+# Optional traditional-provider fallback. Add this option to TRANSLATION_MODELS
+# only when a DeepL-compatible endpoint and key are configured.
+TRANSLATION_API_KEY = os.getenv("TRANSLATION_API_KEY")
+TRANSLATION_API_URL = os.getenv(
+    "TRANSLATION_API_URL", "https://api-free.deepl.com/v2/translate"
+)
+if TRANSLATION_API_KEY:
+    TRANSLATION_MODELS += (("deepl_fallback", "DeepL · Traditional fallback"),)
 # Or for Google Translate:
-# TRANSLATION_API_URL = 'https://translation.googleapis.com/language/translate/v2'
+# TRANSLATION_API_URL = 'https://translation.googleapis.com/language/translate/v2'

translator_app/translator_project/urls.py

@@ -15,8 +15,9 @@ Including another URLconf
     2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
 """
 from django.contrib import admin
-from django.urls import path
+from django.urls import include, path
 
 urlpatterns = [
     path('admin/', admin.site.urls),
+    path('', include('translator.urls')),
 ]