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)
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

git clone <url-du-depot>
cd office_translator

2. Configurer les variables d'environnement

cp .env.example .env

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

# 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) :

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

Environnement de production :

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

# 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)

# 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)

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)

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) :

# 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