README.md

---
title: Translator-API
emoji: 💻
colorFrom: purple
colorTo: gray
sdk: docker
pinned: true
---

# 🌐 Translator API

> **Alternative gratuite à Google Translate** — API REST sans clé, auto-hébergée, avec dashboard admin temps réel.

[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
[![Docker](https://img.shields.io/badge/Docker-ready-blue.svg)](https://docker.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## ✨ Fonctionnalités

| Fonctionnalité | Description |
|---|---|
| 🆓 **Gratuit & Sans clé API** | Pas d'inscription, pas de quota mensuel |
| ⚡ **Rate limiting** | 30 requêtes/minute par IP |
| 🌍 **100+ langues** | Support complet ISO 639-1 + détection auto |
| 📊 **Dashboard Admin** | Métriques CPU/RAM temps réel, logs, graphiques 120s |
| ⚖️ **Architecture distribuée** | Central (API + 1 core) + Workers (1 core) |
| 🔐 **Auth admin sécurisée** | Code d'accès via variables d'environnement |
| 🐳 **Docker ready** | Déploiement 1-click sur HuggingFace Spaces |
| 📚 **Wiki intégré** | Exemples JS, Python, Java, cURL |

---

## 🚀 Démarrage rapide

### Option 1 : Docker Compose (Recommandé)

```bash
# 1. Cloner le repo
git clone https://github.com/NathMen12/Translator-API.git
cd Translator-API

# 2. Configurer les secrets
cp .env.example .env
# Éditer .env avec votre ADMIN_ACCESS_CODE

# 3. Lancer
docker-compose up -d

# 4. Accéder à l'API
curl -X POST http://localhost:7820/translate \
  -H "Content-Type: application/json" \
  -d '{"text": "Bonjour le monde", "source": "fr", "target": "en"}'
```

### Option 2 : Développement local

```bash
# Installer les dépendances
npm install

# Lancer le central (terminal 1)
npm run dev:central

# Lancer le worker (terminal 2)
npm run dev:worker

# Test
curl -X POST http://localhost:7820/translate \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "target": "fr"}'
```

---

## 🌐 Déploiement sur HuggingFace Spaces

1. **Fork ce repo** sur votre GitHub
2. **Créez un Space** sur [huggingface.co/new-space](https://huggingface.co/new-space)
   - SDK: **Docker**
   - Hardware: **CPU Basic (2 vCPU, 16 GB RAM)** ✅
   - Visibility: Public ou Private
3. **Ajoutez les Secrets** dans Settings → Repository secrets :
   - `ADMIN_ACCESS_CODE` = votre mot de passe admin fort
   - `TAILSCALE_API_KEY` = (optionnel) pour découverte workers
4. **Push** → Le Space build et déploie automatiquement !

> ⚠️ Le port **7820** est exposé. HuggingFace Spaces mappe automatiquement sur le port 7860 en externe.

---

## 📖 Utilisation de l'API

### Endpoint principal

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

{
  "text": "Bonjour le monde",
  "source": "fr",     // optionnel, défaut: "auto"
  "target": "en"      // optionnel, défaut: "fr"
}
```

### Réponse

```json
{
  "translatedText": "Hello world",
  "source": "fr",
  "target": "en",
  "duration": 245
}
```

### Codes d'erreur

| Code | Signification |
|------|--------------|
| 200 | Succès |
| 400 | Requête invalide (texte manquant, trop long >5000 chars) |
| 429 | Rate limit dépassé (30 req/min/IP) |
| 500 | Erreur serveur |

---

## 💻 Exemples d'intégration

### JavaScript / TypeScript

```javascript
// Fetch API (navigateur / Node 18+)
async function translate(text, source = 'auto', target = 'fr') {
  const res = await fetch('https://VOTRE_SPACE.hf.space/translate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text, source, target })
  });
  
  if (!res.ok) throw new Error((await res.json()).error);
  return res.json();
}

// Utilisation
translate('Bonjour', 'fr', 'es').then(r => console.log(r.translatedText)); // "Hola"
```

### Python

```python
import requests

def translate(text, source='auto', target='fr', base_url='https://VOTRE_SPACE.hf.space'):
    resp = requests.post(f'{base_url}/translate', 
        json={'text': text, 'source': source, 'target': target}, timeout=30)
    resp.raise_for_status()
    return resp.json()

# Usage
print(translate('Hello world', 'en', 'fr')['translatedText'])  # "Bonjour le monde"
```

### Java (HttpClient 11+)

```java
var client = HttpClient.newHttpClient();
var body = "{\"text\":\"Bonjour\",\"source\":\"fr\",\"target\":\"en\"}";
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://VOTRE_SPACE.hf.space/translate"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
// Parse JSON pour obtenir translatedText
```

### cURL

```bash
curl -X POST https://VOTRE_SPACE.hf.space/translate \
  -H "Content-Type: application/json" \
  -d '{"text": "Bonjour", "source": "fr", "target": "en"}'
```

> 📖 **Plus d'exemples** : Visitez `/wiki` sur votre instance déployée !

---

## 🔐 Panel Admin

Accédez à `https://VOTRE_SPACE.hf.space/admin` et entrez votre `ADMIN_ACCESS_CODE`.

### Onglets disponibles :

| Onglet | Contenu |
|--------|---------|
| 🖥️ **Machines** | CPU/RAM temps réel (central + workers), jobs actifs |
| 📈 **Requêtes (120s)** | Graphique requêtes/minute, stats, taux actuel |
| 📋 **Logs** | Dernières traductions : IP, durée, langues, entrée/sortie |

---

## ⚙️ Configuration

### Central (`central/settings.json`)

```json
{
  "port": 7820,
  "rateLimit": { "maxRequestsPerMinutePerIP": 30, "windowMs": 60000 },
  "scanLocalWorkers": true,
  "metricsWindowSeconds": 120,
  "maxLocalJobs": 4
}
```

### Worker (`worker/settings.json`)

```json
{
  "maxConcurrentJobs": 2,
  "centralHost": "localhost",
  "centralPort": 7820
}
```

### Variables d'environnement (Secrets)

| Variable | Requis | Description |
|----------|--------|-------------|
| `ADMIN_ACCESS_CODE` | ✅ | Mot de passe admin (fort !) |
| `TAILSCALE_API_KEY` | ❌ | Clé API Tailscale pour auto-découverte workers |
| `PORT` | ❌ | Port d'écoute (défaut: 7820) |

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────┐
│                   HUGGINGFACE SPACE                  │
│  ┌─────────────────────┐    ┌────────────────────┐  │
│  │     CENTRAL         │    │      WORKER        │  │
│  │  (1.5 CPU / 12GB)   │◄───│  (0.5 CPU / 4GB)   │  │
│  │  • Express API      │ WS │  • Translation     │  │
│  │  • Rate Limiting    │    │  • Job Queue       │  │
│  │  • Job Dispatch     │    │  • Metrics Push    │  │
│  │  • Admin Dashboard  │    │                    │  │
│  │  • Metrics Storage  │    │                    │  │
│  └─────────────────────┘    └────────────────────┘  │
└─────────────────────────────────────────────────────┘
```

- **Central** : Gère l'API HTTP, rate limiting, dispatch vers workers, dashboard
- **Worker** : Se connecte en WebSocket, exécute les traductions, pousse métriques
- **Communication** : WebSocket natif (ws) pour faible latence

---

## 📦 Structure du projet

```
Translator-API/
├── central/                 # Machine centrale
│   ├── src/index.js        # Serveur Express + WS + Admin
│   ├── settings.json       # Config centrale
│   ├── public/             # Frontend statique
│   │   ├── index.html      # Page d'accueil + test
│   │   ├── admin.html      # Dashboard admin (Chart.js)
│   │   └── wiki.html       # Documentation intégrée
│   └── secrets/            # .env (ignoré par git)
├── worker/                  # Worker de traduction
│   ├── src/index.js        # Client WS + file d'attente
│   └── settings.json       # Config worker
├── shared/                  # Code partagé (futur)
├── wiki/                    # Docs markdown (source)
├── Dockerfile              # Multi-stage build
├── docker-compose.yml      # Orchestration locale
├── .env.example            # Template secrets
└── package.json            # Dépendances root
```

---

## 🛠️ Développement

```bash
# Installer tout
npm run install:all

# Central en mode watch
npm run dev:central

# Worker en mode watch  
npm run dev:worker

# Tests
npm test
```

### Logs

- Central : `central/logs/central.log`
- Worker : `worker/logs/worker.log`

---

## 🔒 Sécurité

- **Pas de clé API publique** — Protection par rate limiting IP
- **Admin protégé** — Code fort dans variable d'environnement (pas dans le code)
- **Secrets HF Spaces** — Stockés chiffrés, injectés au runtime
- **Non-root Docker** — User `nodejs` (UID 1001)
- **Helmet/CORS** — Configurables selon besoins

---

## 📝 Licence

MIT License — Voir [LICENSE](LICENSE)

---

## 🤝 Contribution

1. Fork le projet
2. Créez une branche (`git checkout -b feature/amazing`)
3. Committez (`git commit -m 'Add amazing feature'`)
4. Push (`git push origin feature/amazing`)
5. Ouvrez une Pull Request

---

## 🙏 Remerciements

- [@vitalets/google-translate-api](https://github.com/vitalets/google-translate-api) — Moteur de traduction
- [Chart.js](https://www.chartjs.org/) — Graphiques admin
- [HuggingFace Spaces](https://huggingface.co/spaces) — Hébergement gratuit

---

<div align="center">
  <strong>Fait avec ❤️ par <a href="https://github.com/NathMen12">NathMen12</a></strong>
  <br>
  <a href="https://github.com/NathMen12/Translator-API">⭐ Star sur GitHub</a> • 
  <a href="https://github.com/NathMen12/Translator-API/issues">🐛 Signaler un bug</a> • 
  <a href="https://github.com/NathMen12/Translator-API/discussions">💬 Discussions</a>
</div>