README.md

---
title: Translation Engine API
emoji: 🌍
colorFrom: indigo
colorTo: green
sdk: docker
app_port: 7860
pinned: false
short_description: Multi-model Translation API powered by CTranslate2
---

# 🌍 Translation Engine API

A high-performance, multi-engine Translation API built with **FastAPI** and **Scalar**. 

This Space serves local CPU-optimized machine learning models alongside cloud API providers. It is designed to act as the primary translation backend for an upcoming **Django web application**, but functions completely as a **standalone REST API**.

---

## Interactive API Documentation

Interactive Scalar documentation is hosted directly on the root endpoint:
👉 **[Open API Docs & Sandbox](/scalar)**

---

## Available Translation Engines

### 1. Local CPU Models (Offline & Private)
Local models are automatically downloaded, quantized to **INT8 / GGUF** format, and cached in ephemeral storage for fast CPU execution with minimal RAM footprint.

| Model ID | Provider Name | Base Weights | Precision | Target Languages / Features |
| :--- | :--- | :--- | :--- | :--- |
| `nllb` | **NLLB-200 (600M)** | Meta `nllb-200-distilled-600M` | `int8` | Fast general translation (200+ languages) |
| `nllb_1_3b` | **NLLB-200 (1.3B)** | Meta `nllb-200-distilled-1.3B` | `int8` | Higher accuracy general translation |
| `afrinllb` | **AfriNLLB (600M)** | `AfriNLP/AfriNLLB-12enc-12dec-full-ft-kd` | `int8` | Knowledge-distilled for 15+ African languages |
| `madlad` | **MADLAD-400 (3B)** | `google/madlad400-3b-mt` | `int8` | Multilingual translation across 400+ languages |
| `swahili_gemma` | **Swahili Gemma (1B)** | `CraneAILabs/swahili-gemma-1b-GGUF` | `Q4_K_M` | Fine-tuned for English ↔ Swahili translation |

### 2. Cloud API Engines (Bring-Your-Own-Key)
Cloud API providers allow accessing large language models. You can either configure environment variables on the server or pass your API key dynamically in the JSON payload per request.

| Provider ID | Provider Name | Default Model | Required Client Key |
| :--- | :--- | :--- | :--- |
| `gemini` | **Google Gemini** | `gemini-1.5-flash` | `api_key` (Gemini API Key) |
| `groq` | **Groq LLaMA** | `llama-3.3-70b-versatile` | `api_key` (Groq API Key) |
| `groq_qwen` | **Groq Qwen** | `qwen-2.5-coder-32b` | `api_key` (Groq API Key) |

---

## How to Use the API

### 1. Check Available Engines
```bash
GET /
```

### 2. Translate via Local Model (e.g., AfriNLLB)
```bash
POST /translate
Content-Type: application/json

{
    "text": "Is it not a beautiful Tuesday morning?",
    "source": "eng_Latn",
    "target": "swh_Latn",
    "engine": "afrinllb"
  }
```

### 3. Translate via Cloud API (Passing API Key dynamically)
If no server-side API key is set, clients can supply their own key directly:

```bash
POST /translate
Content-Type: application/json

{
  "provider": "gemini",
  "text": "Good morning, how can I help you today?",
  "src": "en",
  "tgt": "sw",
  "api_key": "YOUR_GEMINI_API_KEY_HERE"
}
```

---

## Environment Variables Configuration

If you are hosting this Space yourself or running it locally, you can set optional environment keys in Space Settings:

```env
# Optional Cloud Keys (If set, clients do not need to provide their own keys)
GEMINI_API_KEY=your_gemini_key
GROQ_API_KEY=your_groq_key

# CTranslate2 / CPU Threading Controls
OMP_NUM_THREADS=8
CT2_COMPUTE_TYPE=int8
```

---

## 📜 Citations & Credits

This project builds upon open-source research and model checkpoints from the AI community:

### AfriNLLB
```bibtex
@inproceedings{moslem-etal-2026-afrinllb,
    title = "{A}fri{NLLB}: Efficient Translation Models for African Languages",
    author = "Moslem, Yasmin and Wassie, Aman Kassahun and Gizachew, Amanuel",
    booktitle = "Proceedings of the Seventh Workshop on African Natural Language Processing (AfricaNLP)",
    year = "2026",
    publisher = "Association for Computational Linguistics"
}
```

### Swahili Gemma
* Fine-tuned and quantized GGUF weights provided by [Crane AI Labs](https://huggingface.co/CraneAILabs/swahili-gemma-1b-GGUF).

### Meta NLLB-200 & Google MADLAD-400
* Meta AI: *No Language Left Behind: Scaling Human-Centered Machine Translation*
* Google Research: *MADLAD-400: A Multilingual Machine Translation Dataset and Model*
```