current changes + deployment

.gitignore

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

Dockerfile

@@ -0,0 +1,36 @@
+# FastAPI model-serving container for Hugging Face Docker Spaces.
+# The Django project owns the user-facing frontend.
+
+# ---- Stage 1: convert NLLB to CTranslate2 int8 (needs torch, build-only) ----
+FROM python:3.11-slim AS model
+WORKDIR /m
+COPY backend/requirements.txt backend/requirements-convert.txt backend/convert_model.py ./
+RUN pip install --no-cache-dir -r requirements.txt \
+ && pip install --no-cache-dir -r requirements-convert.txt --extra-index-url https://download.pytorch.org/whl/cpu
+# CTranslate2 wheels ship a .so that requests an executable stack, which hardened
+# container runtimes (incl. HuggingFace Spaces) refuse. Clear the flag.
+RUN apt-get update && apt-get install -y --no-install-recommends patchelf \
+ && find /usr/local/lib/python3.11/site-packages -name '*.so*' -path '*ctranslate2*' -exec patchelf --clear-execstack {} + \
+ && apt-get purge -y patchelf && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*
+RUN python convert_model.py   # writes ./models/nllb-200-distilled-600M-int8
+RUN HF_MODEL=facebook/nllb-200-distilled-1.3B \
+    CT2_MODEL_DIR=models/nllb-200-distilled-1.3B-int8 \
+    python convert_model.py
+# MADLAD-400: fetch the pre-converted CTranslate2 int8 (model + tokenizer, ~3 GB)
+RUN python -c "from huggingface_hub import snapshot_download; snapshot_download('Nextcloud-AI/madlad400-3b-mt-ct2-int8', local_dir='models/madlad400-3b-mt-int8')"
+
+# ---- Stage 2: lean API runtime (no torch) ----
+FROM python:3.11-slim AS runtime
+WORKDIR /app
+ENV HF_HUB_DISABLE_SYMLINKS_WARNING=1 \
+    MADLAD_HF_MODEL=/app/models/madlad400-3b-mt-int8
+COPY backend/requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+# Same execstack fix for the runtime inference library.
+RUN apt-get update && apt-get install -y --no-install-recommends patchelf \
+ && find /usr/local/lib/python3.11/site-packages -name '*.so*' -path '*ctranslate2*' -exec patchelf --clear-execstack {} + \
+ && apt-get purge -y patchelf && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*
+COPY backend/ ./
+COPY --from=model /m/models ./models
+EXPOSE 7860
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

backend/.env.example

@@ -0,0 +1,25 @@
+# Copy to .env (local) or set as HuggingFace Space secrets.
+# Every engine is optional — the app exposes whichever ones are configured.
+
+# Google Gemini (free tier, no credit card): https://aistudio.google.com/apikey
+GEMINI_API_KEY=
+# GEMINI_MODEL=gemini-2.5-flash-lite
+
+# Groq (free tier, no credit card): https://console.groq.com/keys
+GROQ_API_KEY=
+# GROQ_MODEL=llama-3.3-70b-versatile
+
+# Local NLLB / MADLAD (CTranslate2). Defaults are fine; override for GPU:
+# CT2_DEVICE=cuda
+# CT2_COMPUTE_TYPE=int8
+
+# Local LLM via Ollama (unlocks Qwen / Gemma / TranslateGemma / Aya / Llama).
+# Install Ollama, then `ollama pull <model>`. Engine appears when Ollama runs.
+# OLLAMA_MODEL=qwen2.5
+# OLLAMA_HOST=http://localhost:11434
+
+# MADLAD-400 (local, 400+ languages). Convert once (see README), then it appears:
+# MADLAD_MODEL_DIR=models/madlad400-3b-mt-int8
+
+# Comma-separated allowed origins for the frontend (dev: http://localhost:3000)
+# CORS_ORIGINS=*

backend/Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Only what convert_model.py actually needs — copy this BEFORE the rest of the app
+COPY convert_model.py .
+RUN python convert_model.py
+
+# Now copy everything else — app code changes no longer touch the layer above
+COPY . .
+
+EXPOSE 8000
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/HUGGINGFACE_DEPLOYMENT.md

@@ -0,0 +1,114 @@
+# Deploy the model API to Hugging Face Spaces
+
+This guide deploys the FastAPI model server in `backend/` as a Hugging Face
+Docker Space. The Space is API-only: Django remains responsible for the user
+interface.
+
+## Before you begin
+
+- A Hugging Face account with a write access token.
+- Git and Docker available locally if you will build or test the image yourself.
+- Enough Space hardware and storage for the included model artifacts. The image
+  builds NLLB-200 600M, NLLB-200 1.3B, and MADLAD-400 3B; the first build can
+  take a long time and download several GB.
+
+## Create the Space
+
+1. On [Hugging Face Spaces](https://huggingface.co/new-space), create a new
+   Space.
+2. Choose **Docker** for the SDK and select hardware appropriate for model
+   inference. CPU is suitable for NLLB but will be slower; MADLAD is much more
+   practical on a larger CPU or GPU Space.
+3. Give the Space a name, such as `translator-model-api`.
+
+The repository-root `Dockerfile` is the file Hugging Face builds. It exposes
+port `7860`, which matches the Space `app_port` in the deployment script.
+
+## Deploy from this repository
+
+From the repository root, set your token and Space identifier, then run:
+
+```bash
+HF_TOKEN=hf_your_write_token \
+SPACE_ID=your-hf-user/translator-model-api \
+python backend/deploy_hf.py
+```
+
+The helper creates the Space when needed, uploads the source without local
+model/cache files, and writes Docker Space front matter into the Space README.
+Alternatively, push this repository to the Space Git remote; Hugging Face will
+run the same root `Dockerfile`.
+
+## Wait for the build
+
+Open the Space’s **Logs** tab. A successful build starts Uvicorn and binds to
+port `7860`. The first build converts the NLLB checkpoints and downloads the
+MADLAD CTranslate2 model, so it is substantially slower than later rebuilds.
+
+When the Space is running, its public API base looks like this:
+
+```text
+https://your-hf-user-translator-model-api.hf.space
+```
+
+## Verify the API
+
+Check that an engine is available:
+
+```bash
+curl https://your-hf-user-translator-model-api.hf.space/api/health
+curl https://your-hf-user-translator-model-api.hf.space/api/engines
+```
+
+Send a translation request using the backend’s FLORES-200 language codes:
+
+```bash
+curl -X POST https://your-hf-user-translator-model-api.hf.space/api/translate \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "text": "Hello, how are you?",
+    "source": "eng_Latn",
+    "target": "swh_Latn",
+    "engine": "nllb"
+  }'
+```
+
+Expected response shape:
+
+```json
+{
+  "translation": "…",
+  "source": "eng_Latn",
+  "target": "swh_Latn",
+  "engine": "nllb"
+}
+```
+
+Available engine identifiers are `nllb`, `nllb_1_3b`, and `madlad`. Confirm
+their availability through `/api/engines`; an engine is only usable after its
+model directory exists in the container.
+
+## Connect Django
+
+In `translator_app/.env`, set the translation endpoint to the deployed Space:
+
+```env
+MODEL_API_URL=https://your-hf-user-translator-model-api.hf.space/api/translate
+TRANSLATION_DEFAULT_MODEL=nllb_600m
+```
+
+Restart Django after changing `.env`. The app maps its UI languages to
+FLORES-200 codes, sends the selected model engine to the Space, and stores the
+model choice in history.
+
+## Troubleshooting
+
+- **Build runs out of disk or memory:** choose larger Space hardware/storage,
+  or remove unneeded model build steps from the root `Dockerfile`.
+- **`No translation engine is configured`:** inspect `/api/engines` and Space
+  logs; the model directory was not built or copied correctly.
+- **Django reports the ML service cannot complete the request:** verify
+  `MODEL_API_URL`, confirm the Space is running, and test `/api/translate` with
+  `curl` first.
+- **Slow first request:** models load lazily on their first translation. Keep
+  the Space awake or send a small warm-up request after deployment.

backend/convert_model.py

@@ -0,0 +1,46 @@
+"""Download the NLLB-200 model from HuggingFace and convert it to CTranslate2
+int8 format for fast, low-memory CPU inference.
+
+Run once before starting the server:
+
+    python convert_model.py
+
+This produces ~600 MB in ``models/nllb-200-distilled-600M-int8`` (vs ~2.4 GB
+for the fp32 HuggingFace checkpoint).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+HF_MODEL = os.environ.get("HF_MODEL", "facebook/nllb-200-distilled-600M")
+OUT_DIR = os.environ.get("CT2_MODEL_DIR", "models/nllb-200-distilled-600M-int8")
+QUANTIZATION = os.environ.get("CT2_COMPUTE_TYPE", "int8")
+
+
+def main() -> int:
+    if os.path.isdir(OUT_DIR):
+        print(f"Model already converted at '{OUT_DIR}'. Nothing to do.")
+        return 0
+
+    os.makedirs(os.path.dirname(OUT_DIR) or ".", exist_ok=True)
+    # Invoke via `-m` so it works without the Scripts dir on PATH (Windows venvs).
+    cmd = [
+        sys.executable, "-m", "ctranslate2.converters.transformers",
+        "--model", HF_MODEL,
+        "--output_dir", OUT_DIR,
+        "--quantization", QUANTIZATION,
+    ]
+    print("Running:", " ".join(cmd))
+    result = subprocess.run(cmd)
+    if result.returncode == 0:
+        print(f"\nDone. CTranslate2 model written to '{OUT_DIR}'.")
+    else:
+        print("\nConversion failed.", file=sys.stderr)
+    return result.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

backend/deploy_hf.py

@@ -0,0 +1,76 @@
+"""Deploy this repo to a HuggingFace Space (Docker SDK).
+
+Usage:
+    HF_TOKEN=hf_xxx SPACE_ID=<user>/nllb-translator python deploy_hf.py
+
+Creates the Space if needed, uploads the repo (excluding heavy/ignored dirs),
+and writes a Space README with the required Docker-Space frontmatter.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from huggingface_hub import HfApi
+
+TOKEN = os.environ.get("HF_TOKEN")
+if not TOKEN:
+    sys.exit("Set HF_TOKEN (a write token from https://huggingface.co/settings/tokens)")
+
+api = HfApi(token=TOKEN)
+user = api.whoami()["name"]
+space_id = os.environ.get("SPACE_ID", f"{user}/nllb-translator")
+repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+FRONTMATTER = """---
+title: NLLB Translator w/ django
+emoji: :)
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+"""
+
+IGNORE = [
+    ".git/**",
+    "_reference/**",
+    "**/__pycache__/**",
+    "backend/.venv/**",
+    "backend/models/**",
+    "**/*.pyc",
+]
+
+print(f"Deploying to Space: {space_id}")
+api.create_repo(space_id, repo_type="space", space_sdk="docker", exist_ok=True)
+
+# Upload the repo tree (skip README — replaced below with a frontmatter version).
+api.upload_folder(
+    folder_path=repo_root,
+    repo_id=space_id,
+    repo_type="space",
+    ignore_patterns=IGNORE + ["README.md"],
+    commit_message="Deploy multi-engine NLLB translator",
+)
+
+with open(os.path.join(repo_root, "README.md"), encoding="utf-8") as f:
+    readme = FRONTMATTER + f.read()
+api.upload_file(
+    path_or_fileobj=readme.encode("utf-8"),
+    path_in_repo="README.md",
+    repo_id=space_id,
+    repo_type="space",
+    commit_message="Add Space frontmatter",
+)
+
+print(f"\nDone → https://huggingface.co/spaces/{space_id}")
+print(
+    "The Space will build the Docker image (downloads + converts the model, ~2.4 GB)."
+)
+print(
+    "The Space exposes an API only; configure Django MODEL_API_URL with its /api/translate URL."
+)

backend/languages.py

@@ -0,0 +1,229 @@
+"""FLORES-200 language codes supported by NLLB-200, mapped to readable names.
+
+Each code is `<iso639-3>_<script>` (e.g. ``kor_Hang``). This is the full set of
+languages the NLLB-200 model can translate between.
+"""
+
+# code -> human-readable English display name
+LANGUAGES: dict[str, str] = {
+    "ace_Arab": "Acehnese (Arabic)",
+    "ace_Latn": "Acehnese (Latin)",
+    "acm_Arab": "Mesopotamian Arabic",
+    "acq_Arab": "Ta'izzi-Adeni Arabic",
+    "aeb_Arab": "Tunisian Arabic",
+    "afr_Latn": "Afrikaans",
+    "ajp_Arab": "South Levantine Arabic",
+    "aka_Latn": "Akan",
+    "amh_Ethi": "Amharic",
+    "apc_Arab": "North Levantine Arabic",
+    "arb_Arab": "Modern Standard Arabic",
+    "arb_Latn": "Modern Standard Arabic (Latin)",
+    "ars_Arab": "Najdi Arabic",
+    "ary_Arab": "Moroccan Arabic",
+    "arz_Arab": "Egyptian Arabic",
+    "asm_Beng": "Assamese",
+    "ast_Latn": "Asturian",
+    "awa_Deva": "Awadhi",
+    "ayr_Latn": "Central Aymara",
+    "azb_Arab": "South Azerbaijani",
+    "azj_Latn": "North Azerbaijani",
+    "bak_Cyrl": "Bashkir",
+    "bam_Latn": "Bambara",
+    "ban_Latn": "Balinese",
+    "bel_Cyrl": "Belarusian",
+    "bem_Latn": "Bemba",
+    "ben_Beng": "Bengali",
+    "bho_Deva": "Bhojpuri",
+    "bjn_Arab": "Banjar (Arabic)",
+    "bjn_Latn": "Banjar (Latin)",
+    "bod_Tibt": "Standard Tibetan",
+    "bos_Latn": "Bosnian",
+    "bug_Latn": "Buginese",
+    "bul_Cyrl": "Bulgarian",
+    "cat_Latn": "Catalan",
+    "ceb_Latn": "Cebuano",
+    "ces_Latn": "Czech",
+    "cjk_Latn": "Chokwe",
+    "ckb_Arab": "Central Kurdish",
+    "crh_Latn": "Crimean Tatar",
+    "cym_Latn": "Welsh",
+    "dan_Latn": "Danish",
+    "deu_Latn": "German",
+    "dik_Latn": "Southwestern Dinka",
+    "dyu_Latn": "Dyula",
+    "dzo_Tibt": "Dzongkha",
+    "ell_Grek": "Greek",
+    "eng_Latn": "English",
+    "epo_Latn": "Esperanto",
+    "est_Latn": "Estonian",
+    "eus_Latn": "Basque",
+    "ewe_Latn": "Ewe",
+    "fao_Latn": "Faroese",
+    "pes_Arab": "Western Persian",
+    "fij_Latn": "Fijian",
+    "fin_Latn": "Finnish",
+    "fon_Latn": "Fon",
+    "fra_Latn": "French",
+    "fur_Latn": "Friulian",
+    "fuv_Latn": "Nigerian Fulfulde",
+    "gla_Latn": "Scottish Gaelic",
+    "gle_Latn": "Irish",
+    "glg_Latn": "Galician",
+    "grn_Latn": "Guarani",
+    "guj_Gujr": "Gujarati",
+    "hat_Latn": "Haitian Creole",
+    "hau_Latn": "Hausa",
+    "heb_Hebr": "Hebrew",
+    "hin_Deva": "Hindi",
+    "hne_Deva": "Chhattisgarhi",
+    "hrv_Latn": "Croatian",
+    "hun_Latn": "Hungarian",
+    "hye_Armn": "Armenian",
+    "ibo_Latn": "Igbo",
+    "ilo_Latn": "Ilocano",
+    "ind_Latn": "Indonesian",
+    "isl_Latn": "Icelandic",
+    "ita_Latn": "Italian",
+    "jav_Latn": "Javanese",
+    "jpn_Jpan": "Japanese",
+    "kab_Latn": "Kabyle",
+    "kac_Latn": "Jingpho",
+    "kam_Latn": "Kamba",
+    "kan_Knda": "Kannada",
+    "kas_Arab": "Kashmiri (Arabic)",
+    "kas_Deva": "Kashmiri (Devanagari)",
+    "kat_Geor": "Georgian",
+    "knc_Arab": "Central Kanuri (Arabic)",
+    "knc_Latn": "Central Kanuri (Latin)",
+    "kaz_Cyrl": "Kazakh",
+    "kbp_Latn": "Kabiye",
+    "kea_Latn": "Kabuverdianu",
+    "khm_Khmr": "Khmer",
+    "kik_Latn": "Kikuyu",
+    "kin_Latn": "Kinyarwanda",
+    "kir_Cyrl": "Kyrgyz",
+    "kmb_Latn": "Kimbundu",
+    "kon_Latn": "Kikongo",
+    "kor_Hang": "Korean",
+    "kmr_Latn": "Northern Kurdish",
+    "lao_Laoo": "Lao",
+    "lvs_Latn": "Standard Latvian",
+    "lij_Latn": "Ligurian",
+    "lim_Latn": "Limburgish",
+    "lin_Latn": "Lingala",
+    "lit_Latn": "Lithuanian",
+    "lmo_Latn": "Lombard",
+    "ltg_Latn": "Latgalian",
+    "ltz_Latn": "Luxembourgish",
+    "lua_Latn": "Luba-Kasai",
+    "lug_Latn": "Ganda",
+    "luo_Latn": "Luo",
+    "lus_Latn": "Mizo",
+    "mag_Deva": "Magahi",
+    "mai_Deva": "Maithili",
+    "mal_Mlym": "Malayalam",
+    "mar_Deva": "Marathi",
+    "min_Latn": "Minangkabau",
+    "mkd_Cyrl": "Macedonian",
+    "plt_Latn": "Plateau Malagasy",
+    "mlt_Latn": "Maltese",
+    "mni_Beng": "Meitei (Bengali)",
+    "khk_Cyrl": "Halh Mongolian",
+    "mos_Latn": "Mossi",
+    "mri_Latn": "Maori",
+    "zsm_Latn": "Standard Malay",
+    "mya_Mymr": "Burmese",
+    "nld_Latn": "Dutch",
+    "nno_Latn": "Norwegian Nynorsk",
+    "nob_Latn": "Norwegian Bokmal",
+    "npi_Deva": "Nepali",
+    "nso_Latn": "Northern Sotho",
+    "nus_Latn": "Nuer",
+    "nya_Latn": "Nyanja",
+    "oci_Latn": "Occitan",
+    "gaz_Latn": "West Central Oromo",
+    "ory_Orya": "Odia",
+    "pag_Latn": "Pangasinan",
+    "pan_Guru": "Eastern Panjabi",
+    "pap_Latn": "Papiamento",
+    "pol_Latn": "Polish",
+    "por_Latn": "Portuguese",
+    "prs_Arab": "Dari",
+    "pbt_Arab": "Southern Pashto",
+    "quy_Latn": "Ayacucho Quechua",
+    "ron_Latn": "Romanian",
+    "run_Latn": "Rundi",
+    "rus_Cyrl": "Russian",
+    "sag_Latn": "Sango",
+    "san_Deva": "Sanskrit",
+    "sat_Olck": "Santali",
+    "scn_Latn": "Sicilian",
+    "shn_Mymr": "Shan",
+    "sin_Sinh": "Sinhala",
+    "slk_Latn": "Slovak",
+    "slv_Latn": "Slovenian",
+    "smo_Latn": "Samoan",
+    "sna_Latn": "Shona",
+    "snd_Arab": "Sindhi",
+    "som_Latn": "Somali",
+    "sot_Latn": "Southern Sotho",
+    "spa_Latn": "Spanish",
+    "als_Latn": "Tosk Albanian",
+    "srd_Latn": "Sardinian",
+    "srp_Cyrl": "Serbian",
+    "ssw_Latn": "Swati",
+    "sun_Latn": "Sundanese",
+    "swe_Latn": "Swedish",
+    "swh_Latn": "Swahili",
+    "szl_Latn": "Silesian",
+    "tam_Taml": "Tamil",
+    "tat_Cyrl": "Tatar",
+    "tel_Telu": "Telugu",
+    "tgk_Cyrl": "Tajik",
+    "tgl_Latn": "Tagalog",
+    "tha_Thai": "Thai",
+    "tir_Ethi": "Tigrinya",
+    "taq_Latn": "Tamasheq (Latin)",
+    "taq_Tfng": "Tamasheq (Tifinagh)",
+    "tpi_Latn": "Tok Pisin",
+    "tsn_Latn": "Tswana",
+    "tso_Latn": "Tsonga",
+    "tuk_Latn": "Turkmen",
+    "tum_Latn": "Tumbuka",
+    "tur_Latn": "Turkish",
+    "twi_Latn": "Twi",
+    "tzm_Tfng": "Central Atlas Tamazight",
+    "uig_Arab": "Uyghur",
+    "ukr_Cyrl": "Ukrainian",
+    "umb_Latn": "Umbundu",
+    "urd_Arab": "Urdu",
+    "uzn_Latn": "Northern Uzbek",
+    "vec_Latn": "Venetian",
+    "vie_Latn": "Vietnamese",
+    "war_Latn": "Waray",
+    "wol_Latn": "Wolof",
+    "xho_Latn": "Xhosa",
+    "ydd_Hebr": "Eastern Yiddish",
+    "yor_Latn": "Yoruba",
+    "yue_Hant": "Yue Chinese (Cantonese)",
+    "zho_Hans": "Chinese (Simplified)",
+    "zho_Hant": "Chinese (Traditional)",
+    "zul_Latn": "Zulu",
+}
+
+
+def is_valid(code: str) -> bool:
+    return code in LANGUAGES
+
+
+def name_for(code: str) -> str:
+    """Human-readable name for a FLORES-200 code (used in API prompts)."""
+    return LANGUAGES.get(code, code)
+
+
+def as_list() -> list[dict[str, str]]:
+    """Return languages as a sorted list of {code, name} for the API."""
+    return [
+        {"code": code, "name": name}
+        for code, name in sorted(LANGUAGES.items(), key=lambda kv: kv[1])
+    ]

backend/main.py

@@ -0,0 +1,105 @@
+"""FastAPI service — model-serving API consumed by the Django application."""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+from fastapi import FastAPI, Header, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+import providers
+from languages import as_list
+
+app = FastAPI(
+    title="Translator Model API",
+    description="Model-serving API for the Django Translator App.",
+    version="2.0.0",
+)
+
+_origins = os.environ.get("CORS_ORIGINS", "*").split(",")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[o.strip() for o in _origins],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+MAX_INPUT_CHARS = int(os.environ.get("MAX_INPUT_CHARS", "5000"))
+
+
+class TranslateRequest(BaseModel):
+    text: str = Field(..., description="Text to translate.")
+    source: str = Field(..., description="Source FLORES-200 code, e.g. 'eng_Latn'.")
+    target: str = Field(..., description="Target FLORES-200 code, e.g. 'kor_Hang'.")
+    engine: str | None = Field(None, description="Engine id; defaults to first available.")
+
+
+class TranslateResponse(BaseModel):
+    translation: str
+    source: str
+    target: str
+    engine: str
+
+
+@app.get("/api/health")
+def health() -> dict:
+    return {"status": "ok", "default_engine": providers.default_id()}
+
+
+@app.get("/api/engines")
+def engines() -> dict:
+    return {
+        "engines": [vars(i) for i in providers.all_infos()],
+        "default": providers.default_id(),
+    }
+
+
+@app.get("/api/languages")
+def languages() -> dict:
+    return {"languages": as_list()}
+
+
+@app.post("/api/translate", response_model=TranslateResponse)
+def translate_endpoint(
+    req: TranslateRequest,
+    x_gemini_key: str | None = Header(default=None),
+    x_groq_key: str | None = Header(default=None),
+) -> TranslateResponse:
+    if not req.text.strip():
+        return TranslateResponse(
+            translation="", source=req.source, target=req.target, engine=req.engine or ""
+        )
+    if len(req.text) > MAX_INPUT_CHARS:
+        raise HTTPException(400, f"Input too long (max {MAX_INPUT_CHARS} chars).")
+
+    engine_id = req.engine or providers.default_id()
+    if not engine_id:
+        raise HTTPException(503, "No translation engine is configured.")
+    provider = providers.get(engine_id)
+    if provider is None:
+        raise HTTPException(400, f"Unknown engine: {engine_id!r}")
+
+    # Client-supplied key (bring-your-own-key) for API engines.
+    client_keys = {"gemini": x_gemini_key, "groq": x_groq_key}
+    api_key = client_keys.get(provider.key_field) if provider.key_field else None
+
+    if provider.kind == "api":
+        if not (provider.is_available() or api_key):
+            raise HTTPException(503, provider.setup_hint or "Add an API key in Settings.")
+    elif not provider.is_available():
+        raise HTTPException(503, provider.setup_hint or f"Engine '{engine_id}' is not available.")
+
+    try:
+        result = provider.translate(req.text, req.source, req.target, api_key=api_key)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    except httpx.HTTPStatusError as exc:
+        raise HTTPException(502, f"Upstream API error: {exc.response.status_code}") from exc
+    except Exception as exc:  # noqa: BLE001 — surface engine errors to the client
+        raise HTTPException(500, f"Translation failed: {exc}") from exc
+
+    return TranslateResponse(
+        translation=result, source=req.source, target=req.target, engine=engine_id
+    )

backend/providers/__init__.py

@@ -0,0 +1,53 @@
+"""Registry of translation engines.
+
+Add a new engine by implementing ``TranslationProvider`` and appending an
+instance to ``_PROVIDERS`` below. The API automatically exposes whichever ones
+report themselves available.
+"""
+
+from __future__ import annotations
+
+from providers.base import ProviderInfo, TranslationProvider
+from providers.gemini import GeminiProvider
+from providers.groq import GroqProvider, GroqQwenProvider
+from providers.madlad import MADLADProvider
+from providers.nllb import NLLBProvider
+from providers.ollama import OllamaProvider
+
+# Order = display order in the UI. Local/private engines first.
+_PROVIDERS: list[TranslationProvider] = [
+    NLLBProvider(),
+    NLLBProvider(
+        provider_id="nllb_1_3b",
+        name="NLLB-200 (1.3B)",
+        model_dir="models/nllb-200-distilled-1.3B-int8",
+        hf_model="facebook/nllb-200-distilled-1.3B",
+    ),
+    MADLADProvider(),
+    OllamaProvider(),
+    GeminiProvider(),
+    GroqQwenProvider(),
+    GroqProvider(),
+]
+
+_BY_ID = {p.id: p for p in _PROVIDERS}
+
+
+def all_infos() -> list[ProviderInfo]:
+    return [p.info() for p in _PROVIDERS]
+
+
+def available_infos() -> list[ProviderInfo]:
+    return [p.info() for p in _PROVIDERS if p.is_available()]
+
+
+def get(provider_id: str) -> TranslationProvider | None:
+    return _BY_ID.get(provider_id)
+
+
+def default_id() -> str | None:
+    """First available engine, preferring local/private ones."""
+    for p in _PROVIDERS:
+        if p.is_available():
+            return p.id
+    return None

backend/providers/base.py

@@ -0,0 +1,56 @@
+"""Common interface every translation engine implements.
+
+A *provider* is one translation engine — a local model (NLLB, MADLAD…) or a
+free-tier cloud API (Gemini, Groq…). The registry exposes whichever ones are
+actually usable: a local engine is available when its model files exist; an API
+engine is available when its API key is configured (server env) OR supplied by
+the client per-request (bring-your-own-key).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ProviderInfo:
+    id: str
+    name: str
+    kind: str  # "local" | "api"
+    description: str
+    available: bool  # ready from server-side config (env key / local model)
+    private: bool  # True if text never leaves the machine
+    setup_hint: str  # what to do when unavailable
+    key_field: str  # which client key unlocks it ("gemini"/"groq"); "" for local
+
+
+class TranslationProvider:
+    id: str = ""
+    name: str = ""
+    kind: str = "local"
+    description: str = ""
+    private: bool = False
+    setup_hint: str = ""
+    key_field: str = ""
+
+    def is_available(self) -> bool:
+        raise NotImplementedError
+
+    def translate(self, text: str, src: str, tgt: str, api_key: str | None = None) -> str:
+        raise NotImplementedError
+
+    def display_name(self) -> str:
+        """Overridable so engines like Ollama can reflect the active model."""
+        return self.name
+
+    def info(self) -> ProviderInfo:
+        return ProviderInfo(
+            id=self.id,
+            name=self.display_name(),
+            kind=self.kind,
+            description=self.description,
+            available=self.is_available(),
+            private=self.private,
+            setup_hint=self.setup_hint,
+            key_field=self.key_field,
+        )

backend/providers/gemini.py

@@ -0,0 +1,56 @@
+"""Google Gemini engine — free API tier, no self-hosting.
+
+Uses Gemini's generous free tier (no credit card). Strong on Korean / CJK and
+low-resource prose. Available whenever ``GEMINI_API_KEY`` is set. Text is sent to
+Google, so this engine is not private.
+"""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from languages import name_for
+from providers.base import TranslationProvider
+
+MODEL = os.environ.get("GEMINI_MODEL", "gemini-2.5-flash-lite")
+ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models"
+
+
+class GeminiProvider(TranslationProvider):
+    id = "gemini"
+    name = "Gemini 2.5 Flash-Lite"
+    kind = "api"
+    description = "Google Gemini · free API tier · excellent for Korean/CJK"
+    private = False
+    key_field = "gemini"
+    setup_hint = "Add a Gemini key in Settings (free at aistudio.google.com/apikey)"
+
+    def is_available(self) -> bool:
+        return bool(os.environ.get("GEMINI_API_KEY"))
+
+    def translate(self, text: str, src: str, tgt: str, api_key: str | None = None) -> str:
+        key = api_key or os.environ.get("GEMINI_API_KEY")
+        if not key:
+            raise ValueError("No Gemini API key provided.")
+        prompt = (
+            f"Translate the following text from {name_for(src)} to "
+            f"{name_for(tgt)}. Output ONLY the translation, with no notes, "
+            f"quotes, or explanations.\n\n{text}"
+        )
+        url = f"{ENDPOINT}/{MODEL}:generateContent?key={key}"
+        resp = httpx.post(
+            url,
+            json={
+                "contents": [{"parts": [{"text": prompt}]}],
+                "generationConfig": {"temperature": 0.2},
+            },
+            timeout=30.0,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        try:
+            return data["candidates"][0]["content"]["parts"][0]["text"].strip()
+        except (KeyError, IndexError) as exc:
+            raise RuntimeError(f"Unexpected Gemini response: {data}") from exc

backend/providers/groq.py

@@ -0,0 +1,74 @@
+"""Groq engine(s) — free API tier, ultra-fast LPU inference.
+
+Serves open LLMs via an OpenAI-compatible endpoint. One API key (`GROQ_API_KEY`)
+powers every Groq engine; each subclass just points at a different model.
+Text is sent to Groq, so these engines are not private.
+"""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from languages import name_for
+from providers.base import TranslationProvider
+
+ENDPOINT = "https://api.groq.com/openai/v1/chat/completions"
+
+
+class _GroqEngine(TranslationProvider):
+    kind = "api"
+    private = False
+    key_field = "groq"
+    setup_hint = "Add a Groq key in Settings (free at console.groq.com/keys)"
+    model = ""  # subclass sets this
+
+    def is_available(self) -> bool:
+        return bool(os.environ.get("GROQ_API_KEY"))
+
+    def translate(self, text: str, src: str, tgt: str, api_key: str | None = None) -> str:
+        key = api_key or os.environ.get("GROQ_API_KEY")
+        if not key:
+            raise ValueError("No Groq API key provided.")
+        resp = httpx.post(
+            ENDPOINT,
+            headers={"Authorization": f"Bearer {key}"},
+            json={
+                "model": self.model,
+                "temperature": 0.2,
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": "You are a translation engine. Output only the "
+                        "translation of the user's text, with no notes or quotes.",
+                    },
+                    {
+                        "role": "user",
+                        "content": f"Translate from {name_for(src)} to "
+                        f"{name_for(tgt)}:\n\n{text}",
+                    },
+                ],
+            },
+            timeout=30.0,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        try:
+            return data["choices"][0]["message"]["content"].strip()
+        except (KeyError, IndexError) as exc:
+            raise RuntimeError(f"Unexpected Groq response: {data}") from exc
+
+
+class GroqProvider(_GroqEngine):
+    id = "groq"
+    name = "Llama 3.3 70B (Groq)"
+    description = "Open LLM on Groq · free API tier · very fast"
+    model = os.environ.get("GROQ_MODEL", "llama-3.3-70b-versatile")
+
+
+class GroqQwenProvider(_GroqEngine):
+    id = "groq_qwen"
+    name = "Qwen 2.5 32B (Groq)"
+    description = "Alibaba Qwen 2.5 on Groq · free API · strong CJK/Korean"
+    model = os.environ.get("GROQ_QWEN_MODEL", "qwen-2.5-32b")

backend/providers/madlad.py

@@ -0,0 +1,106 @@
+"""MADLAD-400 engine — local inference via CTranslate2 (int8).
+
+Google's open T5-based MT model covering 400+ languages, generally higher
+quality than NLLB. Heavier than NLLB (3B), so it's a local/GPU engine — not the
+free-CPU-Space default. Convert it once with:
+
+    HF_MODEL=google/madlad400-3b-mt \\
+    CT2_MODEL_DIR=models/madlad400-3b-mt-int8 \\
+    python convert_model.py
+
+MADLAD selects the target language via a ``<2xx>`` token prefixed to the input;
+the source language is auto-detected.
+"""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from threading import Lock
+
+from providers.base import TranslationProvider
+
+MODEL_DIR = os.environ.get("MADLAD_MODEL_DIR", "models/madlad400-3b-mt-int8")
+HF_MODEL = os.environ.get("MADLAD_HF_MODEL", "google/madlad400-3b-mt")
+DEVICE = os.environ.get("CT2_DEVICE", "cpu")
+COMPUTE_TYPE = os.environ.get("CT2_COMPUTE_TYPE", "int8")
+MAX_DECODING_LENGTH = int(os.environ.get("MAX_DECODING_LENGTH", "256"))
+
+# FLORES-200 code -> MADLAD-400 language code (common subset).
+FLORES_TO_MADLAD: dict[str, str] = {
+    "eng_Latn": "en", "kor_Hang": "ko", "jpn_Jpan": "ja", "zho_Hans": "zh",
+    "zho_Hant": "zh", "yue_Hant": "yue", "spa_Latn": "es", "fra_Latn": "fr",
+    "deu_Latn": "de", "rus_Cyrl": "ru", "por_Latn": "pt", "ita_Latn": "it",
+    "nld_Latn": "nl", "pol_Latn": "pl", "tur_Latn": "tr", "arb_Arab": "ar",
+    "hin_Deva": "hi", "ben_Beng": "bn", "vie_Latn": "vi", "tha_Thai": "th",
+    "ind_Latn": "id", "zsm_Latn": "ms", "ukr_Cyrl": "uk", "ces_Latn": "cs",
+    "ron_Latn": "ro", "ell_Grek": "el", "heb_Hebr": "iw", "swe_Latn": "sv",
+    "dan_Latn": "da", "fin_Latn": "fi", "nob_Latn": "no", "hun_Latn": "hu",
+    "bul_Cyrl": "bg", "hrv_Latn": "hr", "srp_Cyrl": "sr", "slk_Latn": "sk",
+    "slv_Latn": "sl", "lit_Latn": "lt", "lvs_Latn": "lv", "est_Latn": "et",
+    "cat_Latn": "ca", "tgl_Latn": "tl", "pes_Arab": "fa", "urd_Arab": "ur",
+    "tam_Taml": "ta", "tel_Telu": "te", "mal_Mlym": "ml", "kan_Knda": "kn",
+    "mar_Deva": "mr", "guj_Gujr": "gu", "pan_Guru": "pa", "mya_Mymr": "my",
+    "khm_Khmr": "km", "lao_Laoo": "lo", "sin_Sinh": "si", "amh_Ethi": "am",
+    "swh_Latn": "sw", "yor_Latn": "yo", "ibo_Latn": "ig", "hau_Latn": "ha",
+    "zul_Latn": "zu", "afr_Latn": "af", "isl_Latn": "is", "gle_Latn": "ga",
+    "cym_Latn": "cy", "eus_Latn": "eu", "glg_Latn": "gl", "kat_Geor": "ka",
+    "hye_Armn": "hy", "azj_Latn": "az", "kaz_Cyrl": "kk", "uzn_Latn": "uz",
+    "mkd_Cyrl": "mk", "als_Latn": "sq", "bel_Cyrl": "be", "npi_Deva": "ne",
+}
+
+
+class MADLADProvider(TranslationProvider):
+    id = "madlad"
+    name = "MADLAD-400 (3B)"
+    kind = "local"
+    description = "Google's open MT model · 400+ languages · higher quality than NLLB"
+    private = True
+    setup_hint = "Convert MADLAD locally (see README — heavy, ~3 GB)"
+
+    def __init__(self) -> None:
+        self._translator = None
+        self._tokenizer = None
+        self._lock = Lock()
+
+    def is_available(self) -> bool:
+        return os.path.isdir(MODEL_DIR)
+
+    def _ensure_loaded(self) -> None:
+        if self._translator is not None:
+            return
+        with self._lock:
+            if self._translator is not None:
+                return
+            import ctranslate2
+            import transformers
+
+            self._translator = ctranslate2.Translator(
+                MODEL_DIR, device=DEVICE, compute_type=COMPUTE_TYPE
+            )
+            self._tokenizer = transformers.AutoTokenizer.from_pretrained(HF_MODEL)
+
+    @lru_cache(maxsize=2048)
+    def _translate_line(self, text: str, madlad_tgt: str) -> str:
+        prompt = f"<2{madlad_tgt}> {text}"
+        source = self._tokenizer.convert_ids_to_tokens(self._tokenizer.encode(prompt))
+        results = self._translator.translate_batch(
+            [source], beam_size=4, max_decoding_length=MAX_DECODING_LENGTH
+        )
+        target_tokens = results[0].hypotheses[0]
+        return self._tokenizer.decode(
+            self._tokenizer.convert_tokens_to_ids(target_tokens)
+        )
+
+    def translate(self, text: str, src: str, tgt: str, api_key: str | None = None) -> str:
+        madlad_tgt = FLORES_TO_MADLAD.get(tgt)
+        if madlad_tgt is None:
+            raise ValueError(
+                "MADLAD engine doesn't support this target language yet — "
+                "try NLLB, or pick a more common language."
+            )
+        self._ensure_loaded()
+        out = []
+        for line in text.split("\n"):
+            out.append(self._translate_line(line, madlad_tgt) if line.strip() else "")
+        return "\n".join(out)

backend/providers/nllb.py

@@ -0,0 +1,83 @@
+"""NLLB-200 engine — local inference via CTranslate2 (int8).
+
+Light enough to run on a free HuggingFace Spaces CPU. Heavy objects load lazily
+on first use and are shared across requests.
+"""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from threading import Lock
+
+from languages import is_valid
+from providers.base import TranslationProvider
+
+MODEL_DIR = os.environ.get("CT2_MODEL_DIR", "models/nllb-200-distilled-600M-int8")
+HF_MODEL = os.environ.get("HF_MODEL", "facebook/nllb-200-distilled-600M")
+DEVICE = os.environ.get("CT2_DEVICE", "cpu")
+COMPUTE_TYPE = os.environ.get("CT2_COMPUTE_TYPE", "int8")
+MAX_DECODING_LENGTH = int(os.environ.get("MAX_DECODING_LENGTH", "256"))
+
+
+class NLLBProvider(TranslationProvider):
+    kind = "local"
+    description = "Meta's open translation model · 200 languages · runs offline"
+    private = True
+    setup_hint = "Convert the model: `python convert_model.py`"
+
+    def __init__(
+        self,
+        provider_id: str = "nllb",
+        name: str = "NLLB-200 (600M)",
+        model_dir: str = MODEL_DIR,
+        hf_model: str = HF_MODEL,
+    ) -> None:
+        self.id = provider_id
+        self.name = name
+        self.model_dir = model_dir
+        self.hf_model = hf_model
+        self._translator = None
+        self._tokenizer = None
+        self._lock = Lock()
+
+    def is_available(self) -> bool:
+        return os.path.isdir(self.model_dir)
+
+    def _ensure_loaded(self) -> None:
+        if self._translator is not None:
+            return
+        with self._lock:
+            if self._translator is not None:
+                return
+            import ctranslate2
+            import transformers
+
+            self._translator = ctranslate2.Translator(
+                self.model_dir, device=DEVICE, compute_type=COMPUTE_TYPE
+            )
+            self._tokenizer = transformers.AutoTokenizer.from_pretrained(self.hf_model)
+
+    @lru_cache(maxsize=2048)
+    def _translate_line(self, text: str, src: str, tgt: str) -> str:
+        self._tokenizer.src_lang = src
+        source = self._tokenizer.convert_ids_to_tokens(self._tokenizer.encode(text))
+        results = self._translator.translate_batch(
+            [source],
+            target_prefix=[[tgt]],
+            beam_size=4,
+            max_decoding_length=MAX_DECODING_LENGTH,
+        )
+        target_tokens = results[0].hypotheses[0][1:]  # drop the target-lang token
+        return self._tokenizer.decode(
+            self._tokenizer.convert_tokens_to_ids(target_tokens)
+        )
+
+    def translate(self, text: str, src: str, tgt: str, api_key: str | None = None) -> str:
+        if not is_valid(src) or not is_valid(tgt):
+            raise ValueError("Unknown language code for NLLB.")
+        self._ensure_loaded()
+        out = []
+        for line in text.split("\n"):
+            out.append(self._translate_line(line, src, tgt) if line.strip() else "")
+        return "\n".join(out)

backend/providers/ollama.py

@@ -0,0 +1,65 @@
+"""Ollama engine — any local LLM, fully offline.
+
+One provider unlocks a whole shelf of open models the user can run locally via
+Ollama: Qwen, Gemma / TranslateGemma, Aya, Llama, and more. Set the model with
+``OLLAMA_MODEL`` (default ``qwen2.5``); pull it first with ``ollama pull <model>``.
+
+Available whenever a local Ollama server is reachable. Text never leaves the
+machine, so this engine is private.
+"""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from languages import name_for
+from providers.base import TranslationProvider
+
+HOST = os.environ.get("OLLAMA_HOST", "http://localhost:11434").rstrip("/")
+MODEL = os.environ.get("OLLAMA_MODEL", "qwen2.5")
+
+
+class OllamaProvider(TranslationProvider):
+    id = "ollama"
+    name = "Local LLM (Ollama)"
+    kind = "local"
+    description = "Run Qwen / Gemma / TranslateGemma / Aya locally · offline"
+    private = True
+    setup_hint = "Install Ollama and `ollama pull " + MODEL + "`"
+
+    def display_name(self) -> str:
+        return f"{MODEL} (Ollama)"
+
+    def is_available(self) -> bool:
+        try:
+            resp = httpx.get(f"{HOST}/api/tags", timeout=0.4)
+            return resp.status_code == 200
+        except httpx.HTTPError:
+            return False
+
+    def translate(self, text: str, src: str, tgt: str, api_key: str | None = None) -> str:
+        resp = httpx.post(
+            f"{HOST}/api/chat",
+            json={
+                "model": MODEL,
+                "stream": False,
+                "options": {"temperature": 0.2},
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": "You are a translation engine. Output only the "
+                        "translation of the user's text, with no notes or quotes.",
+                    },
+                    {
+                        "role": "user",
+                        "content": f"Translate from {name_for(src)} to "
+                        f"{name_for(tgt)}:\n\n{text}",
+                    },
+                ],
+            },
+            timeout=120.0,
+        )
+        resp.raise_for_status()
+        return resp.json()["message"]["content"].strip()

backend/requirements-convert.txt

@@ -0,0 +1,4 @@
+# Extra deps needed ONLY to convert the HF model to CTranslate2 (one-time).
+# Runtime inference does not need torch. Install with the CPU wheel index:
+#   pip install -r requirements-convert.txt --extra-index-url https://download.pytorch.org/whl/cpu
+torch==2.5.1

backend/requirements.txt

@@ -0,0 +1,14 @@
+# API
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+pydantic==2.10.4
+httpx==0.28.1
+
+# Local inference (NLLB via CTranslate2; no torch needed at runtime)
+ctranslate2==4.5.0
+transformers==4.47.1
+sentencepiece==0.2.0
+protobuf==5.29.2
+
+# ctranslate2 4.5 imports pkg_resources, removed in setuptools>=81
+setuptools<81

docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  backend:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "7860:7860"
+    env_file:
+      - path: ./backend/.env
+        required: false
+    environment:
+      - CORS_ORIGINS=http://localhost:8000
+      # API engines activate automatically when these are set (see backend/.env)
+      - GEMINI_API_KEY=${GEMINI_API_KEY:-}
+      - GROQ_API_KEY=${GROQ_API_KEY:-}
+    volumes:
+      # Persist the converted model + HF cache across rebuilds.
+      - model-cache:/app/models
+      - hf-cache:/root/.cache/huggingface
+
+volumes:
+  model-cache:
+  hf-cache:

requirements.txt

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