sepehr
5fd087979b
All checks were successful
Deploy to Production / Build and Deploy (push) Successful in 2m21s
348 lines
11 KiB
Markdown
348 lines
11 KiB
Markdown
# 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`) |
|
|
| DeepSeek / Minimax | LLM | Oui (`DEEPSEEK_API_KEY` / `MINIMAX_API_KEY`) |
|
|
| 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
|
|
|
|
|
|
|
|
### 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** : OpenAI / DeepSeek / Minimax (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 DeepSeek/Minimax : vérifier que la clé API correspondante est configurée
|
|
|
|
### 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, DeepSeek, etc.)
|
|
│ ├── 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
|
|
```
|