rpa_vision_v3/.kiro/specs/real-demo-localization/design.md

Design : Localisation du Composant RealDemo

Architecture de Solution

Vue d'ensemble

L'implémentation de la localisation du composant RealDemo s'appuie sur l'architecture existante du système de localisation RPA Vision V3, sans modification structurelle.

Diagramme de Flux

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   RealDemo      │───▶│ useLocalization  │───▶│ Traductions     │
│   Component     │    │ Hook             │    │ JSON            │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │                       ▼                       │
         │              ┌──────────────────┐             │
         │              │ LocalizationSvc  │             │
         │              │ (existant)       │             │
         │              └──────────────────┘             │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Interface       │    │ Cache & State    │    │ Validation      │
│ Utilisateur     │    │ Management       │    │ Automatique     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Modifications Requises

1. Composant RealDemo

Avant (Code Actuel)

const RealDemo: React.FC<RealDemoProps> = ({ onWorkflowExecute }) => {
  return (
    <Box sx={{ p: 3 }}>
      <Typography variant="h5" gutterBottom>
        Démonstration Réelle - RPA Vision V3
      </Typography>
      
      <Typography variant="body1" paragraph>
        Ce composant permettra de tester le système RPA en temps réel.
      </Typography>
      
      <Button
        variant="contained"
        startIcon={<PlayIcon />}
        onClick={handleExecute}
        sx={{ mt: 2 }}
      >
        Démarrer la Démonstration
      </Button>
    </Box>
  );
};

Après (Code Localisé)

import { useLocalization } from '../../services/LocalizationService';

const RealDemo: React.FC<RealDemoProps> = ({ onWorkflowExecute }) => {
  const { t } = useLocalization();

  return (
    <Box sx={{ p: 3 }}>
      <Typography variant="h5" gutterBottom>
        {t('realDemo.component.title')}
      </Typography>
      
      <Typography variant="body1" paragraph>
        {t('realDemo.component.description')}
      </Typography>
      
      <Button
        variant="contained"
        startIcon={<PlayIcon />}
        onClick={handleExecute}
        sx={{ mt: 2 }}
      >
        {t('realDemo.component.startButton')}
      </Button>
    </Box>
  );
};

2. Nouvelles Clés de Traduction

Structure JSON à Ajouter

{
  "realDemo": {
    // ... clés existantes ...
    "component": {
      "title": "Démonstration Réelle - RPA Vision V3",
      "description": "Ce composant permettra de tester le système RPA en temps réel.",
      "startButton": "Démarrer la Démonstration"
    }
  }
}

Traductions par Langue

Français (fr.json) - Référence

{
  "realDemo": {
    "component": {
      "title": "Démonstration Réelle - RPA Vision V3",
      "description": "Ce composant permettra de tester le système RPA en temps réel.",
      "startButton": "Démarrer la Démonstration"
    }
  }
}

Anglais (en.json)

{
  "realDemo": {
    "component": {
      "title": "Real Demonstration - RPA Vision V3",
      "description": "This component will allow testing the RPA system in real time.",
      "startButton": "Start Demonstration"
    }
  }
}

Espagnol (es.json)

{
  "realDemo": {
    "component": {
      "title": "Demostración Real - RPA Vision V3",
      "description": "Este componente permitirá probar el sistema RPA en tiempo real.",
      "startButton": "Iniciar Demostración"
    }
  }
}

Allemand (de.json)

{
  "realDemo": {
    "component": {
      "title": "Echte Demonstration - RPA Vision V3",
      "description": "Diese Komponente ermöglicht es, das RPA-System in Echtzeit zu testen.",
      "startButton": "Demonstration Starten"
    }
  }
}

Stratégie d'Implémentation

Phase 1 : Préparation des Traductions

1. Analyse du contenu existant

   • Identifier toutes les chaînes à localiser
   • Vérifier la cohérence avec les traductions existantes
   • Définir les nouvelles clés selon les conventions

2. Création des traductions

   • Ajouter les clés dans fr.json (référence)
   • Traduire dans les 3 autres langues
   • Respecter les conventions culturelles

Phase 2 : Modification du Composant

1. Import du service

   • Ajouter l'import useLocalization
   • Initialiser le hook dans le composant
   • Maintenir la compatibilité TypeScript

2. Remplacement des chaînes

   • Remplacer chaque chaîne par un appel t()
   • Vérifier que les clés correspondent
   • Tester le rendu dans chaque langue

Phase 3 : Validation et Tests

1. Validation automatique

   • Exécuter le script de validation Python
   • Corriger les erreurs détectées
   • Vérifier la cohérence des structures

2. Tests d'intégration

   • Tester le changement de langue en temps réel
   • Vérifier la persistance du choix
   • Valider l'affichage dans toutes les langues

Considérations Techniques

TypeScript et Types

// Le hook useLocalization est déjà typé
interface LocalizationHook {
  t: (key: string, params?: Record<string, any>) => string;
  changeLanguage: (language: string) => void;
  currentLanguage: string;
  availableLanguages: Language[];
}

// Utilisation avec autocomplétion
const { t } = useLocalization();
const title = t('realDemo.component.title'); // Type: string

Gestion des Erreurs

// Le service gère automatiquement les fallbacks
const text = t('cle.inexistante'); // Retourne la clé si non trouvée
const text = t('realDemo.component.title'); // Retourne la traduction ou fallback

Performance

• Cache existant : Pas d'impact sur les performances
• Chargement à la demande : Les traductions sont déjà chargées
• Rendu optimisé : React optimise automatiquement les re-rendus

Validation et Qualité

Script de Validation Automatique

# Le script existant détectera automatiquement les nouvelles clés
python i18n/validate_translations.py

# Sortie attendue après implémentation
✅ Chargé: fr.json
✅ Chargé: en.json
✅ Chargé: es.json
✅ Chargé: de.json
📋 Clés de référence (fr): 130  # +3 nouvelles clés
🔍 en: 130 clés (0 manquantes, 0 supplémentaires)
🔍 es: 130 clés (0 manquantes, 0 supplémentaires)
🔍 de: 130 clés (0 manquantes, 0 supplémentaires)

✅ VALIDATION RÉUSSIE: Aucun problème détecté!

Tests de Qualité

1. Cohérence terminologique

   • "Démonstration" vs "Demo" : Utiliser "Démonstration" (cohérent avec l'existant)
   • "RPA Vision V3" : Garder le nom du produit identique
   • "Temps réel" : Cohérent avec les traductions existantes

2. Longueur des textes

   • Titre : ~35 caractères maximum
   • Description : ~80 caractères maximum
   • Bouton : ~25 caractères maximum

3. Conventions culturelles

   • Français : Majuscules sur les noms propres uniquement
   • Anglais : Title Case pour les titres
   • Espagnol : Majuscules minimales, accents respectés
   • Allemand : Majuscules sur les noms, mots composés

Intégration avec l'Existant

Cohérence avec les Traductions Actuelles

// Structure existante à respecter
{
  "realDemo": {
    "title": "Démonstration Réelle",           // Cohérent
    "component": {
      "title": "Démonstration Réelle - RPA Vision V3"  // Extension logique
    }
  }
}

Réutilisation des Patterns

// Pattern existant dans d'autres composants
const { t } = useLocalization();

// Utilisation cohérente
<Typography variant="h5">{t('realDemo.component.title')}</Typography>
<Button>{t('realDemo.component.startButton')}</Button>

Plan de Rollback

En cas de Problème

1. Sauvegarde : Les fichiers originaux sont versionnés
2. Rollback rapide : Restaurer le code sans localisation
3. Validation : Tester que l'interface fonctionne
4. Investigation : Analyser la cause du problème

Stratégie de Déploiement

1. Développement : Implémentation et tests locaux
2. Validation : Tests automatiques et manuels
3. Intégration : Merge dans la branche principale
4. Déploiement : Mise en production progressive

Métriques de Succès

Techniques

• 0 erreur dans la validation automatique
• 100% couverture des chaînes localisées
• Temps de rendu identique ou amélioré
• Taille du bundle impact négligeable

Fonctionnelles

• Interface cohérente dans les 4 langues
• Changement de langue instantané
• Persistance du choix utilisateur
• Expérience utilisateur fluide

Qualité

• Traductions naturelles et idiomatiques
• Respect des conventions culturelles
• Cohérence terminologique avec l'existant
• Accessibilité maintenue

Cette conception assure une intégration harmonieuse du composant RealDemo avec le système de localisation existant, en maintenant la qualité et les performances tout en étendant la couverture multilingue de l'application.