office_translator/GUIDE_UTILISATION.md

# Guide d'utilisation - Office Translator

## Présentation

**Office Translator** est une plateforme SaaS de traduction de documents Office (Excel `.xlsx`, Word `.docx`, PowerPoint `.pptx`) qui préserve le formatage original du document. L'utilisateur dépose un document, le récupère traduit, et le fichier reste visuellement identique à l'original (couleurs, cellules fusionnées, graphiques, mises en page).

### Stack technique

| Composant | Technologie |
|-----------|-------------|
| Backend | Python 3.11+, FastAPI, uvicorn |
| Frontend | Node 20, Next.js 15 |
| Base de données | PostgreSQL 16 (prod) / SQLite (dev) |
| Cache & sessions | Redis 7 |
| Reverse proxy (prod) | Nginx |
| Conteneurisation | Docker + Docker Compose |

### Fournisseurs de traduction supportés

| Fournisseur | Type | Clé API requise |
|-------------|------|----------------|
| Google Translate | Classique | Non (via deep_translator) |
| DeepL | Classique | Oui (`DEEPL_API_KEY`) |
| OpenAI (GPT-4o-mini) | LLM | Oui (`OPENAI_API_KEY`) |
| Ollama (Llama3) | LLM local | Non (local) |
| OpenRouter | LLM | Oui (`OPENROUTER_API_KEY`) |

Les fournisseurs sont utilisés via une **chaîne de fallback** configurable (si un échoue, le suivant prend le relais).

---

## Prérequis

- **Docker** (Engine 20.10+) et **Docker Compose V2** (`docker compose`)
- Un terminal (bash, zsh, PowerShell)
- Pour un lancement sans Docker (dev local) : Python 3.11+, Node 20+, PostgreSQL et Redis optionnel

---

## Méthode 1 : Lancement avec Docker (recommandé)

### 1. Cloner le dépôt

```bash
git clone <url-du-depot>
cd office_translator
```

### 2. Configurer les variables d'environnement

```bash
cp .env.example .env
```

Éditer le fichier `.env` et remplir les champs requis. Voici les variables minimales pour le développement :

```env
# Obligatoire
JWT_SECRET_KEY=<générer avec: python -c "import secrets; print(secrets.token_urlsafe(64))">
ADMIN_USERNAME=admin
ADMIN_PASSWORD=votre_mot_de_passe_admin

# Base de données (Docker s'occupe du reste)
# DATABASE_URL est construit automatiquement par Docker Compose

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8000
```

Pour la **production**, les variables suivantes sont obligatoires (l'application refuse de démarrer sans elles) :

| Variable | Description |
|----------|-------------|
| `JWT_SECRET_KEY` | Clé de signature JWT |
| `ADMIN_USERNAME` | Identifiant admin |
| `ADMIN_PASSWORD` ou `ADMIN_PASSWORD_HASH` | Mot de passe admin |
| `ADMIN_TOKEN_SECRET` | Secret pour les sessions admin |
| `DATABASE_URL` (ou `POSTGRES_*`) | URL de connexion PostgreSQL |
| `REDIS_URL` | URL Redis (si rate limiting activé) |

### 3. Lancer l'application

**Environnement de développement** (avec hot reload) :

```bash
docker compose -f docker-compose.dev.yml up
```

**Environnement de production** :

```bash
docker compose up -d
```

### 4. Vérifier que tout fonctionne

| Service | URL |
|---------|-----|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:8000 |
| Documentation API (Swagger) | http://localhost:8000/docs |
| Documentation API (ReDoc) | http://localhost:8000/redoc |
| Health check | http://localhost:8000/health |

### 5. Arrêter l'application

```bash
# Développement
docker compose -f docker-compose.dev.yml down

# Production
docker compose down
```

> Pour supprimer aussi les volumes (données) : ajouter `--volumes`

---

## Méthode 2 : Lancement local sans Docker (développement)

### 1. Backend (FastAPI)

```bash
# Créer un environnement virtuel
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Installer les dépendances
pip install -r requirements.txt

# Configurer l'environnement
cp .env.example .env
# Éditer .env avec vos valeurs

# Lancer les migrations de base de données
alembic upgrade head

# Lancer le serveur
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

Le backend est accessible sur http://localhost:8000

### 2. Frontend (Next.js)

```bash
cd frontend

# Installer les dépendances
npm install

# Configurer l'URL du backend
# Créer frontend/.env.local avec :
# NEXT_PUBLIC_API_URL=http://localhost:8000

# Lancer en développement
npm run dev
```

Le frontend est accessible sur http://localhost:3000

---

## Services optionnels en production

### Ollama (LLM local)

Pour utiliser un modèle LLM local (Ollama), ajouter le profil `with-ollama` :

```bash
docker compose --profile with-ollama up -d
```

Configurer dans `.env` :

```env
TRANSLATION_SERVICE=ollama
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_MODEL=llama3
```

### Monitoring (Prometheus + Grafana)

```bash
docker compose --profile with-monitoring up -d
```

---

## Utilisation de l'application

### 1. Créer un compte

1. Aller sur http://localhost:3000
2. Cliquer sur **S'inscrire** (Register)
3. Remplir le formulaire d'inscription

### 2. Se connecter

1. Aller sur la page de connexion
2. Entrer email et mot de passe
3. Accéder au tableau de bord (Dashboard)

### 3. Traduire un document

1. Depuis le Dashboard, cliquer sur **Nouvelle traduction**
2. **Uploader** un fichier `.xlsx`, `.docx` ou `.pptx` (max 50 Mo par défaut)
3. **Choisir la langue source** et la **langue cible**
4. **Sélectionner le mode de traduction** :
   - **Classique** : Google Translate / DeepL (rapide, < 15 sec)
   - **LLM** : Ollama / OpenAI (1-3 min, meilleure qualité contextuelle)
5. Cliquer sur **Traduire**
6. Suivre la **barre de progression** en temps réel
7. **Télécharger** le fichier traduit une fois terminé

### 4. Utilisation de l'API REST

L'API est accessible directement (pour les intégrations) :

```bash
# Health check
curl http://localhost:8000/health

# Traduire un document
curl -X POST http://localhost:8000/api/v1/translate \
  -H "Authorization: Bearer <votre_token_jwt>" \
  -F "file=@document.docx" \
  -F "source_lang=fr" \
  -F "target_lang=en" \
  -F "mode=classic"
```

La documentation interactive est disponible sur :
- Swagger UI : http://localhost:8000/docs
- ReDoc : http://localhost:8000/redoc

### 5. Accès Admin

1. Se connecter avec les identifiants admin (configurés dans `.env`)
2. Le tableau de bord admin permet de :
   - Surveiller la santé du système (disque, mémoire, Redis, DB)
   - Gérer les utilisateurs et leurs abonnements (tiers)
   - Consulter les statistiques de traduction
   - Nettoyer manuellement les fichiers temporaires
   - Consulter les logs d'erreurs

---

## Fonctionnalités avancées (plan Pro/Business)

### Glossaires

Créer des glossaires pour garantir la cohérence terminologique lors des traductions LLM :
1. Dashboard > Glossaires
2. Créer un glossaire avec des paires de termes (source → cible)
3. Importer/exporter en CSV

### Prompts personnalisés

Définir des prompts système personnalisés pour les traductions LLM :
1. Dashboard > Custom Prompts
2. Créer un prompt avec les instructions de traduction

### Clés API

Générer des clés API pour accéder au service programmatiquement :
1. Dashboard > API Keys
2. Créer une clé et l'utiliser via le header `X-API-Key`

---

## Dépannage

### L'application ne démarre pas

- **"Missing required env: ..."** : Des variables d'environnement obligatoires sont manquantes. Vérifier le fichier `.env` (voir la section configuration).
- **Port déjà utilisé** : Vérifier que les ports 3000 et 8000 sont libres : `lsof -i :8000` et `lsof -i :3000`.

### Problèmes de connexion base de données

- Vérifier que PostgreSQL est en cours d'exécution : `docker compose ps`
- Vérifier les variables `DATABASE_URL` ou `POSTGRES_*` dans `.env`
- Relancer les migrations : `alembic upgrade head`

### Problèmes Redis

- Vérifier que Redis est en cours d'exécution : `docker compose ps`
- Si `REDIS_URL` n'est pas défini en dev, le rate limiting peut fonctionner en mémoire (fallback)
- En production, `REDIS_URL` est obligatoire si le rate limiting est activé

### Les fichiers ne sont pas traduits

- Vérifier que le fournisseur de traduction est configuré (`TRANSLATION_SERVICE` dans `.env`)
- Pour Google Translate : aucune clé nécessaire
- Pour DeepL/OpenAI : vérifier que la clé API est valide
- Pour Ollama : vérifier que le service est lancé et que le modèle est téléchargé

### Logs

Les logs structurés (JSON en production) sont disponibles :
- Dans le conteneur backend : `docker compose logs backend`
- Dans le dossier `logs/` (monté en volume en production)

---

## Variables d'environnement principales

| Variable | Requise (prod) | Défaut | Description |
|----------|----------------|--------|-------------|
| `ENV` | Non | `development` | Environnement (`development` / `production`) |
| `JWT_SECRET_KEY` | Oui | - | Clé de signature JWT |
| `DATABASE_URL` | Oui | SQLite local | URL PostgreSQL |
| `REDIS_URL` | Oui (si rate limit) | - | URL Redis |
| `TRANSLATION_SERVICE` | Non | `google` | Fournisseur par défaut |
| `ADMIN_USERNAME` | Oui | - | Identifiant admin |
| `ADMIN_PASSWORD` | Oui | - | Mot de passe admin |
| `CORS_ORIGINS` | Non | `http://localhost:3000` | Origines CORS autorisées |
| `NEXT_PUBLIC_API_URL` | Non | `http://localhost:8000` | URL du backend pour le frontend |
| `MAX_FILE_SIZE_MB` | Non | `50` | Taille max des fichiers upload |
| `LOG_LEVEL` | Non | `INFO` | Niveau de logs |
| `RATE_LIMIT_ENABLED` | Non | `true` | Activer le rate limiting |
| `CLEANUP_ENABLED` | Non | `true` | Nettoyage auto des fichiers |

La liste complète et détaillée se trouve dans `.env.example`.

---

## Structure du projet

```
office_translator/
├── main.py                  # Point d'entrée FastAPI
├── config.py                # Configuration (variables d'environnement)
├── requirements.txt         # Dépendances Python
├── alembic.ini              # Configuration migrations DB
├── alembic/                 # Migrations de base de données
├── routes/                  # Endpoints API
├── services/                # Logique métier
│   ├── providers/           # Fournisseurs de traduction (Google, DeepL, OpenAI, Ollama)
│   ├── translation_service.py
│   └── ...
├── translators/             # Traducteurs de documents (Excel, Word, PowerPoint)
├── middleware/               # Middlewares (rate limiting, sécurité, erreurs, cleanup)
├── models/                  # Modèles de base de données
├── schemas/                 # Schémas Pydantic (validation)
├── database/                # Connexion et sessions DB
├── frontend/                # Application Next.js
│   ├── src/app/             # Pages et layout
│   ├── src/components/      # Composants React
│   └── src/messages/        # Fichiers de traduction i18n
├── docker/                  # Fichiers Docker
│   ├── backend/Dockerfile
│   ├── frontend/Dockerfile
│   └── nginx/               # Configuration Nginx (prod)
├── docker-compose.yml       # Docker Compose production
├── docker-compose.dev.yml   # Docker Compose développement
├── scripts/                 # Scripts utilitaires
└── tests/                   # Tests unitaires et d'intégration
```