--- 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 ---
Fait avec ❤️ par NathMen12
⭐ Star sur GitHub • 🐛 Signaler un bug • 💬 Discussions