sepehr/office_translator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a0de00a4e78d44c72f5d554d064b5fbd5b16cf35
office_translator/_bmad-output/planning-artifacts/cdc-design-ia-positioning.md
sepehr b50419e2ec
All checks were successful
Deploy to Production / Build and Deploy (push) Successful in 2s
Details
fix: integrate deepseek, resolve silent google api errors, fix google cloud keys
2026-05-17 17:11:06 +02:00

512 lines
23 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink