# 🌍 Traducteur Automatique i18n JSON — Ingénierie LLM & Robustesse Backend
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://www.docker.com/)
[](https://cloud.google.com/run)
[](https://flask.palletsprojects.com/)
[](https://typer.tiangolo.com/)
[](./run_tests.sh)
[](LICENSE)
Outil de traduction automatique haute performance pour fichiers de localisation web (`.json`) basé sur **Google Gemini (Structured Outputs)**, garantissant la préservation stricte des structures arborescentes et des variables d'interpolation (`{username}`, `{{count}}`, ``).
---
## 🎯 Objectifs & Problématique Métier
Dans les applications web modernes (React, Vue, Angular), la localisation repose sur des dictionnaires JSON complexes et souvent profondément imbriqués. La traduction via un LLM classique pose plusieurs défis majeurs :
1. **Perte de structure** : L'IA peut modifier ou supprimer des clés JSON imbriquées.
2. **Altération des variables** : L'IA a tendance à traduire ou ajouter des espaces dans les variables dynamiques (ex: transformer `{ count }` au lieu de `{count}`).
3. **Limites de taux et fenêtres de contexte** : Envoyer des milliers de phrases en un seul appel provoque des erreurs d'API (Rate Limit 429) ou dépasse les quotas de sortie.
4. **Pannes réseau et coût** : Une coupure réseau mid-stream annule tout le travail et oblige à payer et ré-attendre la traduction depuis le début.
Ce projet résout l'intégralité de ces problématiques grâce à un pipeline robuste en 6 étapes.
---
## 🏗️ Architecture du Pipeline & Découpage Microservice
```mermaid
flowchart TD
subgraph Clients["Clients & IHM"]
CLI[Typer CLI]
DASH[Dashboard Flask Port 5000]
EXT[Clients REST / Google Cloud Run]
end
subgraph Container["Google Cloud Run (Microservice FastAPI Port 8000)"]
API[api/main.py & api/routers/translation.py]
B[Phase 2.1 : Aplatissement / Flattening]
C[Phase 2.3 : Découpage en Lots / Batching]
D[Phase 3 : Gemini Structured Outputs Pydantic]
E[Phase 4.3 : Exponential Backoff & Jitter]
F[Phase 4.1 : Post-traitement Regex]
G[Phase 4.2 : Checkpointing Atomique]
H[Phase 2.2 : Reconstruction / Unflattening]
end
CLI --> B
DASH -->|Proxy /api/*| API
EXT --> API
API --> B
B --> C --> D
D -->|Rate Limit 429 ?| E --> D
D --> F --> G --> H
```
---
## ⚡ Fonctionnalités Clés & Modularité
| Module | Emplacement | Rôle & Description |
| :--- | :--- | :--- |
| **JSON Utils** | [`src/json_utils.py`](file:///home/michael/Code/job/projets/traducteur_i18n/src/json_utils.py) | Algorithmes d'aplatissement récursif (`flatten_json`), de reconstruction (`unflatten_json`) et de segmentation par lots (`chunk_dict`). |
| **Regex Utils** | [`src/regex_utils.py`](file:///home/michael/Code/job/projets/traducteur_i18n/src/regex_utils.py) | Nettoyeur automatique (`post_process_variables`) corrigeant les espaces superflus autour des variables `{user}`, `{{count}}` et balises HTML ``. |
| **Checkpointing** | [`src/checkpoint.py`](file:///home/michael/Code/job/projets/traducteur_i18n/src/checkpoint.py) | Gestionnaire de persistance (`CheckpointManager`) écrivant de manière atomique sur disque (fichier `.tmp` + `fsync` + `rename`) pour reprendre la traduction sans perte après un crash. |
| **Retry & Backoff** | [`src/retry.py`](file:///home/michael/Code/job/projets/traducteur_i18n/src/retry.py) | Décorateur résilient (`retry_with_exponential_backoff`) avec calcul de délai exponentiel ($1s \to 2s \to 4s$) et bruit aléatoire (*Jitter*). |
| **Client LLM** | [`src/llm_client.py`](file:///home/michael/Code/job/projets/traducteur_i18n/src/llm_client.py) | Génération dynamique de modèles Pydantic avec alias virtuels pour forcer Gemini à renvoyer exactement le schéma requis. |
| **Façade Core** | [`src/core.py`](file:///home/michael/Code/job/projets/traducteur_i18n/src/core.py) | Façade unifiée ré-exportant les sous-modules pour une lisibilité maximale et zéro breaking change. |
| **CLI Typer** | [`src/cli.py`](file:///home/michael/Code/job/projets/traducteur_i18n/src/cli.py) | Interface utilisateur en ligne de commande avec options de découpage, ré-essais, et checkpointing. |
| **Microservice FastAPI** | [`api/main.py`](file:///home/michael/Code/job/projets/traducteur_i18n/api/main.py) | Microservice REST cloud de production avec documentation OpenAPI / Swagger (`http://127.0.0.1:8000/docs`). |
| **Script Google Cloud Run** | [`deploy_gcp_cloud_run.sh`](file:///home/michael/Code/job/projets/traducteur_i18n/deploy_gcp_cloud_run.sh) | Script d'automatisation pour build sur Artifact Registry, enregistrement du secret `GEMINI_API_KEY` dans GCP Secret Manager et déploiement serverless Cloud Run. |
| **Dockerfile Multi-Stage** | [`Dockerfile`](file:///home/michael/Code/job/projets/traducteur_i18n/Dockerfile) | Configuration Docker multi-stage optimisée (builder + runner non-root `appuser`) pour le déploiement sur Google Cloud Run. |
| **Docker Compose** | [`docker-compose.yml`](file:///home/michael/Code/job/projets/traducteur_i18n/docker-compose.yml) | Fichier d'orchestration locale pour isoler et exécuter le microservice FastAPI. |
| **Dashboard Flask** | [`dashboard/app.py`](file:///home/michael/Code/job/projets/traducteur_i18n/dashboard/app.py) | SPA web moderne avec bacs à sable interactifs, journal pédagogique et lanceur de tests QA. |
---
## 🚀 Démarrage Rapide
### 1. Installation des dépendances
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. Lancement de la Suite de Tests Unitaires (80 tests)
```bash
./run_tests.sh
```
### 3. Lancement de la CLI Typer
```bash
python3 src/cli.py translate --help
```
### 4. Lancement Simultané des Services (Local)
```bash
./start_services.sh
# 🌐 Dashboard Web SPA (Flask) : http://127.0.0.1:5000/
# ⚡ Microservice API (FastAPI) : http://127.0.0.1:8000/
# 📖 Documentation Swagger API : http://127.0.0.1:8000/docs
```
### 5. Démarrage du Microservice sous Docker
```bash
docker compose up --build
```
### 6. Déploiement Serverless sur Google Cloud Run
```bash
./deploy_gcp_cloud_run.sh --dry-run
# Retirer --dry-run pour exécuter le déploiement réel sur Google Cloud
```
---
## 📚 Documentation & Ressources
- 🔌 **[Guide d'Intégration en Production](file:///home/michael/Code/job/projets/traducteur_i18n/docs/guide_integration_production.md)** : Guide d'intégration pas à pas pour la CLI, le Microservice REST FastAPI sous Docker / Google Cloud Run et l'utilisation comme Module Python.
- 📖 **[Glossaire Technique Complet](file:///home/michael/Code/job/projets/traducteur_i18n/docs/glossaire.md)** : Définitions des termes clés (Structured Outputs, Jitter, Écriture Atomique, Microservice REST, Google Cloud Run, Secret Manager).
- ❓ **[FAQ d'Entretien Technique](file:///home/michael/Code/job/projets/traducteur_i18n/docs/faq_entretien.md)** : 16 questions-réponses approfondies pour préparer les entretiens techniques.
- 📓 **[Journal d'Apprentissage](file:///home/michael/Code/job/projets/traducteur_i18n/docs/journal/phase_5_3_deploiement_google_cloud_run.md)** : 15 chapitres détaillant les arbitrages d'architecture, la conteneurisation Docker et le déploiement GCP Cloud Run.