# Cahier des Charges — Refonte Design & Positionnement IA

**Auteur** : Mary (Business Analyst), basé sur l'audit du 2026-05-08
**Projet** : Office Translator
**Objectif** : Transformer l'IA d'une feature cachée en différentiateur central, et corriger les problèmes UX prioritaires

---

## 1. Contexte et Enjeux

### 1.1 État des lieux

Office Translator dispose d'un moteur de traduction IA complet (DeepSeek V3, Claude 3.5 Haiku, glossaires métier, system prompts, vision sur images). Cependant, l'audit révèle que :

- L'IA est **invisible** pour les utilisateurs Free (provider selector masqué)
- La landing page **ne mentionne pas** la traduction IA comme différenciateur principal
- Les métriques de qualité sont **fictives** (confiance 96% hardcodée, segments 142 hardcodés)
- Plusieurs pages mélangent **texte hardcodé et clés i18n**, cassant l'internationalisation
- Aucune section **"Comment ça marche"**, aucune **preuve sociale**, aucun **playground de démo**

### 1.2 Objectifs mesurables

| KPI | Actuel (estimé) | Cible |
|-----|-----------------|-------|
| Taux de conversion Free → Pro | < 2% | 5-8% |
| Taux de rebond landing page | Inconnu | -30% |
| Feature discovery IA (Free users) | ~0% | 80% |
| Score de confiance utilisateur | Variable (métriques fausses) | Données réelles, toujours pertinentes |

---

## 2. Périmètre des Travaux

### Phase 1 — Correction UX / i18n (P0)
### Phase 2 — Positionnement IA sur la Landing (P1)
### Phase 3 — Freemium IA & Conversion (P1)
### Phase 4 — Enrichissement Landing & Social Proof (P2)
### Phase 5 — Nettoyage technique (P3)

---

## 3. Phase 1 — Correction UX / i18n (P0)

### 3.1 Internationalisation des pages

**Problème** : Les pages `translate/page.tsx`, `services/page.tsx`, et `features-section.tsx` contiennent du texte hardcodé (anglais et français) au lieu d'utiliser les clés i18n.

#### 3.1.1 Page de traduction (`translate/page.tsx`)

Textes à migrer vers i18n :

| Texte hardcodé | Clé i18n proposée | Fichier |
|---|---|---|
| "Source Document" | `dashboard.translate.sourceDocument` | translate/page.tsx |
| "Configuration" | `dashboard.translate.configuration` | translate/page.tsx |
| "Traduction en cours" | `dashboard.translate.translating` | translate/page.tsx |
| "Moniteur en direct" | `dashboard.translate.liveMonitor` | translate/page.tsx |
| "Résumé" | `dashboard.translate.summary` | translate/page.tsx |
| "Moteur" | `dashboard.translate.engine` | translate/page.tsx |
| "Confiance" | `dashboard.translate.confidence` | translate/page.tsx |
| "Annuler" | `dashboard.translate.cancel` | translate/page.tsx |
| "Segments" | `dashboard.translate.segments` | translate/page.tsx |
| "Caractères" | `dashboard.translate.characters` | translate/page.tsx |
| "Écoulé" | `dashboard.translate.elapsed` | translate/page.tsx |
| "Seg/min" | `dashboard.translate.segPerMin` | translate/page.tsx |
| "Haute qualité" | `dashboard.translate.highQuality` | translate/page.tsx |
| "Qualité" | `dashboard.translate.quality` | translate/page.tsx |
| "Traduction terminée" | `dashboard.translate.completed` | translate/page.tsx |
| "Remplacer" | `dashboard.translate.replace` | translate/page.tsx |
| "PDF Translation Mode" | `dashboard.translate.pdfMode.title` | translate/page.tsx |
| "Preserve Layout" | `dashboard.translate.pdfMode.preserveLayout` | translate/page.tsx |
| "Text Only" | `dashboard.translate.pdfMode.textOnly` | translate/page.tsx |
| Descriptions PDF mode (2 paragraphes) | `dashboard.translate.pdfMode.preserveLayoutDesc` / `textOnlyDesc` | translate/page.tsx |
| Labels du pipeline (Upload, Analyse, Traduction, Reconstruction, Finalisation) | `dashboard.translate.pipeline.upload` etc. | translate/page.tsx |

**Critères d'acceptation** :
- Toutes les 13 locales (`en`, `fr`, `es`, `de`, `pt`, `it`, `nl`, `ru`, `ja`, `ko`, `zh`, `ar`, `fa`) doivent avoir une traduction pour chaque clé
- Aucun texte visible en dur dans le code source
- Test visuel sur 3 locales minimum (en, fr, fa) pour vérifier l'affichage

#### 3.1.2 Page Services (`services/page.tsx`)

Textes à migrer :

| Texte hardcodé | Clé i18n proposée |
|---|---|
| "Translation Providers" | `dashboard.services.title` |
| "Providers are configured by the administrator..." | `dashboard.services.subtitle` |
| "Classic Translation" | `dashboard.services.classicTitle` |
| "LLM · Context-Aware (Pro)" | `dashboard.services.llmTitle` |
| "Available" | `dashboard.services.available` |
| "Provider configuration is admin-only" | `dashboard.services.adminOnly.title` |
| Description du panneau admin | `dashboard.services.adminOnly.description` |
| "Loading providers..." | `dashboard.services.loading` |
| "No providers are currently configured..." | `dashboard.services.none` |
| "Model:" | `dashboard.services.model` |

#### 3.1.3 Composant features (`features-section.tsx`)

Ce composant est un composant legacy non utilisé par la landing actuelle (`landing-page.tsx` a sa propre section features). Il doit être soit supprimé, soit intégré avec i18n complète. Voir Phase 5 — section 7.3.

### 3.2 Métriques dynamiques

**Problème** : Les statistiques affichées pendant et après la traduction sont hardcodées et fictives.

#### 3.2.1 Données fictives identifiées

Fichier `translate/page.tsx`, lignes 128-129 :
```typescript
const totalSegments = 142;
const totalChars = 12847;
```

Et le score de confiance est calculé avec une formule arbitraire :
```typescript
Math.min(96, Math.round(82 + submit.progress * 0.14))
```

#### 3.2.2 Solution — Données réelles depuis le backend

**Backend** : L'endpoint de progression (`/api/v1/translate/{session_id}/progress`) doit retourner :

```json
{
  "progress": 65,
  "current_step": "Translating segment 87/134",
  "total_segments": 134,
  "completed_segments": 87,
  "total_chars": 12450,
  "completed_chars": 8092,
  "elapsed_seconds": 23,
  "estimated_remaining_seconds": 12,
  "segments_per_minute": 227,
  "provider": "openrouter"
}
```

**Frontend** : Remplacer les constantes hardcodées par les valeurs retournées par l'API de progression. Si l'API ne retourne pas ces champs, les calculer côté frontend à partir des données disponibles, ou afficher "—" au lieu d'un chiffre inventé.

**Critères d'acceptation** :
- Le nombre de segments affiché correspond au nombre réel de segments dans le document
- Le score de confiance est soit basé sur des métriques réelles, soit retiré et remplacé par un indicateur qualitatif ("Standard" / "Haute précision" selon le provider)
- Aucun chiffre fictif visible par l'utilisateur

### 3.3 Suppression du score de confiance fictif

Si le calcul d'un vrai score de confiance est trop complexe pour cette phase, remplacer par un indicateur qualitatif du provider :

| Provider | Label affiché |
|---|---|
| Google / LibreTranslate | "Traduction standard" |
| DeepL | "Haute qualité" |
| DeepSeek / LLM Essential | "IA Contextuelle" |
| Claude / LLM Premium | "IA Expert — Haute précision" |

Ce label remplace le pourcentage fictif "96%" et est purement informatif, basé sur le type de provider sélectionné.

---

## 4. Phase 2 — Positionnement IA sur la Landing (P1)

### 4.1 Nouvelle section "AI Translation Engine"

**Emplacement** : Sur la landing page (`landing-page.tsx`), entre le Hero et la section "Why Us" existante.

#### 4.1.1 Structure de la section

```
┌──────────────────────────────────────────────────────────┐
│  Badge : 🧠 AI-Powered Translation Engine                │
│                                                          │
│  Titre : La traduction qui comprend votre métier         │
│  Sous-titre : Nos modèles IA analysent le contexte,      │
│  respectent votre terminologie et traduisent même        │
│  le texte dans vos images.                               │
│                                                          │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐       │
│  │ 📋 Contexte │ │ 📖 Glossaire│ │ 👁️ Vision   │       │
│  │             │ │             │ │             │        │
│  │ Décrivez    │ │ Définissez  │ │ Le texte    │       │
│  │ votre       │ │ vos termes  │ │ dans les    │       │
│  │ domaine     │ │ métier      │ │ images est  │       │
│  │ technique   │ │ (CTA=AHU)   │ │ traduit     │       │
│  └─────────────┘ └─────────────┘ └─────────────┘       │
│                                                          │
│  ┌──── Comparaison visuelle ────────────────────────┐   │
│  │  Source (FR) : "La batterie de chauffe est       │   │
│  │                 raccordée sur la CTA"             │   │
│  │                                                    │   │
│  │  Google : "The heating battery is connected       │   │
│  │            on the call to action"   ❌             │   │
│  │                                                    │   │
│  │  Notre IA : "The heating coil is connected        │   │
│  │             to the AHU"             ✅             │   │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
```

#### 4.1.2 Clés i18n de la section

| Clé | FR | EN |
|---|---|---|
| `landing.ai.badge` | Moteur de Traduction IA | AI-Powered Translation Engine |
| `landing.ai.title` | La traduction qui comprend votre métier | Translation that understands your craft |
| `landing.ai.subtitle` | Nos modèles IA analysent le contexte, respectent votre terminologie et traduisent même le texte dans vos images. | Our AI models analyze context, respect your terminology, and even translate text inside images. |
| `landing.ai.context.title` | Contexte métier | Industry Context |
| `landing.ai.context.desc` | Décrivez votre domaine et obtenez des traductions adaptées, pas génériques. | Describe your field and get tailored translations, not generic ones. |
| `landing.ai.glossary.title` | Glossaires métier | Industry Glossaries |
| `landing.ai.glossary.desc` | Définissez vos termes techniques. CTA restera "Air Handling Unit", jamais "Call To Action". | Define your technical terms. CTA stays "Air Handling Unit", never "Call To Action". |
| `landing.ai.vision.title` | Vision sur images | Image Vision |
| `landing.ai.vision.desc` | Le texte incrusté dans vos images, diagrammes et graphiques est détecté et traduit. | Text embedded in images, diagrams and charts is detected and translated. |
| `landing.ai.comparison.source` | Source (FR) | Source (FR) |
| `landing.ai.comparison.google` | Google Translate | Google Translate |
| `landing.ai.comparison.ai` | Notre IA | Our AI |

#### 4.1.3 Critères d'acceptation

- La section est responsive (mobile : colonne unique, desktop : 3 colonnes pour les features)
- L'exemple de comparaison est statique mais réaliste (pas d'appel API)
- L'animation au scroll est fluide (fade-in des cartes)
- La section est entièrement i18n-ready (13 locales)

### 4.2 Section "Comment ça marche"

**Emplacement** : Après la section AI Engine, avant "Why Us".

#### 4.2.1 Structure

```
┌──────────────────────────────────────────────────────────┐
│  Comment ça marche ?                                     │
│                                                          │
│  ① Déposez      ② Configurez     ③ Téléchargez         │
│  ┌────────┐     ┌────────┐       ┌────────┐             │
│  │ Upload │ ──▶ │ Choix  │ ──▶   │ Fichier│             │
│  │ fichier│     │ langue │       │ traduit│             │
│  └────────┘     │ + IA   │       │ + même │             │
│                 └────────┘       │ format │             │
│                                  └────────┘             │
│                                                          │
│  DOCX, XLSX, PPTX, PDF — Votre format est préservé      │
└──────────────────────────────────────────────────────────┘
```

#### 4.2.2 Clés i18n

| Clé | FR | EN |
|---|---|---|
| `landing.howItWorks.title` | Comment ça marche ? | How it works |
| `landing.howItWorks.subtitle` | Trois étapes. Zéro perte de format. | Three steps. Zero formatting loss. |
| `landing.howItWorks.step1.title` | Déposez votre fichier | Upload your file |
| `landing.howItWorks.step1.desc` | Glissez-déposez votre document Excel, Word, PowerPoint ou PDF. | Drag & drop your Excel, Word, PowerPoint or PDF document. |
| `landing.howItWorks.step2.title` | Choisissez la langue et le moteur | Pick language & engine |
| `landing.howItWorks.step2.desc` | Sélectionnez la langue cible et le moteur de traduction — classique ou IA contextuelle. | Select target language and engine — standard or context-aware AI. |
| `landing.howItWorks.step3.title` | Téléchargez le résultat | Download the result |
| `landing.howItWorks.step3.desc` | Récupérez votre document traduit avec un formatage identique à l'original. | Get your translated document with formatting identical to the original. |

### 4.3 Refonte de la section "Why Us" existante

La section actuelle ("Why Us") se concentre sur la préservation du format. Elle doit intégrer l'IA comme dimension :

Ajouter 2 cartes aux 6 existantes :

| Carte | Icône | Clé i18n |
|---|---|---|
| Traduction IA contextuelle | `Brain` | `landing.why.aiContext.title` / `landing.why.aiContext.desc` |
| Glossaires personnalisés | `BookOpen` | `landing.why.glossary.title` / `landing.why.glossary.desc` |

Passer de 6 à 8 cartes, disposées en 2 lignes de 4 sur desktop, 4+4 sur tablette, colonne sur mobile.

---

## 5. Phase 3 — Freemium IA & Conversion (P1)

### 5.1 Visibilité du Provider Selector pour tous les utilisateurs

**Problème actuel** : `translate/page.tsx` ligne 339 : `{config.isPro && (<ProviderSelector ... />)}` — le sélecteur est complètement masqué pour les utilisateurs Free.

**Solution** : Afficher le Provider Selector pour tous les utilisateurs avec les providers LLM en état "verrouillé" :

```
┌─ Provider ──────────────────────────────────┐
│ ○ Google Traduction — 130+ langues          │
│ ○ DeepL — Haute qualité                     │
│                                              │
│ ── ✨ AI · Context-Aware ─── PRO ──         │
│                                              │
│ 🔒 DeepSeek V3 — Contexte + Glossaire       │
│ 🔒 Claude 3.5 Haiku — Haute précision       │
│                                              │
│ → Débloquer l'IA — Essai gratuit           │
└──────────────────────────────────────────────┘
```

**Critères d'acceptation** :
- Les providers "classic" sont utilisables par tous
- Les providers LLM sont visibles mais grisés avec une icône 🔒
- Un CTA "Débloquer l'IA" apparaît sous les providers verrouillés
- Le CTA mène vers la page pricing avec ancre sur le plan Pro
- L'utilisateur Free peut toujours traduire avec les providers classiques

### 5.2 Quota de traductions IA gratuites

**Règle** : Chaque utilisateur Free dispose de **5 crédits IA** par mois.

#### 5.2.1 Backend — Compteur de crédits

- Ajouter un champ `ai_credits_used` et `ai_credits_limit` dans la table utilisateur
- Free : `ai_credits_limit = 5` par mois (reset au 1er de chaque mois)
- Starter : `ai_credits_limit = 0` (pas d'IA)
- Pro : `ai_credits_limit = -1` (illimité)
- Business : `ai_credits_limit = -1` (illimité)

#### 5.2.2 Endpoint API

```
GET /api/v1/auth/me
```
Ajouter dans la réponse :
```json
{
  "ai_credits_used": 2,
  "ai_credits_limit": 5,
  "ai_credits_remaining": 3
}
```

```
POST /api/v1/translate
```
Si l'utilisateur sélectionne un provider LLM et `ai_credits_remaining <= 0`, retourner :
```json
{
  "error": "ai_credits_exhausted",
  "message": "Vous avez utilisé vos 5 traductions IA gratuites ce mois-ci. Passez au plan Pro pour un accès illimité.",
  "upgrade_url": "/pricing"
}
```

#### 5.2.3 Frontend — Affichage du compteur

Dans le Provider Selector, quand un utilisateur Free a des crédits IA restants :
```
✨ AI · Context-Aware — 3/5 essais gratuits ce mois-ci
```

Quand les crédits sont épuisés :
```
✨ AI · Context-Aware — Essais épuisés → Voir les plans
```

### 5.3 Page de démo interactive (Mini-Playground)

**Emplacement** : Landing page, optionnel, section dédiée après la comparaison IA.

#### 5.3.1 Fonctionnement

L'utilisateur saisit une phrase technique (ou choisit un exemple prédéfini) et voit en temps réel la différence entre Google Translate et l'IA avec glossaire.

**Exemples prédéfinis** :
- "La batterie de chauffe est raccordée sur la CTA n°3" (HVAC)
- "Le serveur proxy reverse les requêtes vers le load balancer" (IT)
- "Le tribunal d'instance a prononcé la résiliation du bail" (Legal)

**Backend** : Endpoint dédié sans authentification :
```
POST /api/v1/demo/translate
{
  "text": "La batterie de chauffe est raccordée sur la CTA",
  "source_lang": "fr",
  "target_lang": "en"
}
```

Réponse :
```json
{
  "google": "The heating battery is connected on the CTA",
  "ai": "The heating coil is connected to the AHU",
  "glossary_applied": ["batterie=coil", "CTA=AHU"]
}
```

**Rate limiting** : Maximum 10 requêtes par IP par heure pour éviter l'abus.

**Critères d'acceptation** :
- Fonctionne sans inscription
- Affiche les deux résultats côte à côte
- Surligne les termes où le glossaire a été appliqué
- 3 exemples prédéfinis cliquables
- Champ libre pour saisie personnalisée
- Responsive mobile (résultats empilés)

---

## 6. Phase 4 — Enrichissement Landing & Social Proof (P2)

### 6.1 Section Preuve Sociale

**Emplacement** : Après "How it works", avant le pricing.

#### 6.1.1 Éléments

- **Compteur animé** : "X documents traduits ce mois-ci" (données réelles depuis l'admin dashboard)
- **Logos clients** (si disponibles) ou "Utilisé par des équipes dans X pays"
- **3 témoignages** (citations fictives mais réalistes en attendant de vrais retours) :

| Personne | Contexte | Citation |
|---|---|---|
| Marie D., Responsable CVC | "Nos documents techniques HVAC étaient toujours mal traduits. Avec les glossaires, c'est comme avoir un traducteur spécialisé." |
| Thomas K., DSI | "L'API s'est intégrée en une heure. 200 documents par mois, zéro retouche de mise en page." |
| Sophie L., Cabinet juridique | "Les contrats multilingues nécessitaient 2h de reformatage. Maintenant, c'est immédiat." |

#### 6.1.2 Clés i18n

| Clé | FR |
|---|---|
| `landing.social.title` | Ils traduisent plus intelligemment |
| `landing.social.subtitle` | Des professionnels dans 12 pays font confiance à Office Translator |
| `landing.social.documentsCount` | documents traduits ce mois-ci |

### 6.2 FAQ sur la Landing

Ajouter une section FAQ directement sur la landing page (pas seulement sur /pricing). Questions prioritaires :

1. "Quelle est la différence entre traduction classique et IA ?"
2. "Mon format sera-t-il vraiment préservé ?"
3. "Mes documents sont-ils sécurisés ?"
4. "Puis-je utiliser mes propres termes techniques ?"
5. "Quels formats de fichier sont supportés ?"

---

## 7. Phase 5 — Nettoyage technique (P3)

### 7.1 Suppression des composants legacy

Les fichiers suivants semblent être d'anciennes versions de la landing page, redondants avec `landing-page.tsx` :

- `components/landing/hero-section.tsx` — supprimer (le hero est dans `landing-page.tsx`)
- `components/landing/features-section.tsx` — supprimer (la section features est dans `landing-page.tsx`)

**Action** : Vérifier qu'aucun import ne référence ces fichiers, puis supprimer.

### 7.2 Vérification des imports

Avant suppression, vérifier avec `grep` qu'aucun composant n'importe `HeroSection` ou `FeaturesSection`.

### 7.3 Audit des clés i18n orphelines

Après la Phase 1, certaines clés i18n pourraient ne plus être utilisées. Faire un passage pour identifier et nettoyer les clés mortes.

---

## 8. Matrice de Dépendances

```
Phase 1 (i18n + métriques)
  ├── Bloque rien, mais tout le reste bénéficie d'une base propre
  │
Phase 2 (Landing IA)
  ├── Dépend de Phase 1 pour les clés i18n de la landing
  │
Phase 3 (Freemium IA)
  ├── Dépend partiellement de Phase 2 (CTA "Débloquer l'IA" vers pricing)
  ├── Backend indépendant (compteur crédits)
  ├── Mini-playground peut être parallélisé
  │
Phase 4 (Social proof)
  ├── Indépendant des autres phases
  ├── Peut être fait en parallèle
  │
Phase 5 (Nettoyage)
  └── Faire en dernier, une fois que tout est stable
```

## 9. Estimation d'Effort

| Phase | Effort frontend | Effort backend | Complexité |
|---|---|---|---|
| Phase 1 — i18n + métriques | 2-3 jours | 1 jour (endpoint progress enrichi) | Moyenne |
| Phase 2 — Landing IA | 2 jours | 0 | Faible |
| Phase 3 — Freemium IA | 1 jour | 2 jours (crédits + demo endpoint) | Moyenne |
| Phase 3 — Mini-playground | 1.5 jours | 0.5 jour | Moyenne |
| Phase 4 — Social proof | 1 jour | 0 | Faible |
| Phase 5 — Nettoyage | 0.5 jour | 0 | Faible |
| **Total** | **~8 jours** | **~3.5 jours** | |

## 10. Risques et Mitigations

| Risque | Probabilité | Impact | Mitigation |
|---|---|---|---|
| L'endpoint de progression ne retourne pas les segments | Moyenne | Faible | Afficher "—" au lieu de chiffres faux, et itérer côté backend |
| Les 5 crédits IA Free génèrent un trafic excessif sur les LLM | Faible | Moyenne | Rate limiting strict par IP +监控 des coûts LLM |
| Les témoignages fictifs posent un problème éthique | Faible | Moyenne | Les marquer comme "exemples illustratifs" ou les remplacer par des beta-testeurs réels |
| Traduction de 13 locales pour toutes les nouvelles clés | Élevée | Faible | Commencer par EN + FR, ajouter les autres locales progressivement |

---

## 11. Critères de Succès Globaux

Le cahier des charges sera considéré comme rempli quand :

1. ✅ Aucun texte hardcodé visible dans les pages translate, services, landing
2. ✅ Les métriques de traduction reflètent la réalité du document en cours
3. ✅ La landing page comporte une section IA Engine avec comparaison visuelle
4. ✅ La landing page comporte une section "Comment ça marche"
5. ✅ Le Provider Selector est visible pour les utilisateurs Free (avec LLM verrouillé)
6. ✅ Les utilisateurs Free disposent de 5 crédits IA mensuels
7. ✅ Le score de confiance fictif est remplacé par un indicateur qualitatif réel
8. ✅ Les composants legacy sont supprimés