# Guide de Localisation - RPA Vision V3

> **Système de localisation multilingue pour l'interface utilisateur**  
> Auteur : Dom, Alice, Kiro - 7 janvier 2026

## 🌍 Vue d'Ensemble

Le système de localisation de RPA Vision V3 permet de supporter plusieurs langues dans l'interface utilisateur du Visual Workflow Builder. Il est conçu pour être extensible, performant et facile à utiliser.

### Langues Supportées

- **🇫🇷 Français** (fr) - Langue par défaut
- **🇺🇸 English** (en) - Anglais américain
- **🇪🇸 Español** (es) - Espagnol
- **🇩🇪 Deutsch** (de) - Allemand

## 🏗️ Architecture du Système

### Structure des Fichiers

```
i18n/
├── config.json           # Configuration des langues
├── fr.json              # Traductions françaises
├── en.json              # Traductions anglaises
├── es.json              # Traductions espagnoles
└── de.json              # Traductions allemandes

visual_workflow_builder/frontend/src/
├── services/
│   └── LocalizationService.ts    # Service principal
└── components/
    └── LanguageSelector/         # Sélecteur de langue
        ├── index.tsx
        └── LanguageSelector.css
```

### Configuration (config.json)

```json
{
  "defaultLanguage": "fr",
  "supportedLanguages": [
    {
      "code": "fr",
      "name": "Français",
      "flag": "🇫🇷",
      "dateFormat": "DD/MM/YYYY",
      "timeFormat": "HH:mm",
      "currency": "EUR",
      "currencySymbol": "€",
      "decimalSeparator": ",",
      "thousandsSeparator": " "
    }
  ],
  "fallbackLanguage": "fr",
  "autoDetect": true,
  "persistLanguageChoice": true
}
```

## 🚀 Utilisation

### Dans les Composants React

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

const MonComposant: React.FC = () => {
  const { t, getCurrentLanguage, changeLanguage } = useLocalization();

  return (
    <div>
      <h1>{t('realDemo.title')}</h1>
      <p>{t('realDemo.subtitle')}</p>
      <button onClick={() => changeLanguage('en')}>
        {t('common.language')}
      </button>
    </div>
  );
};
```

### Traductions avec Paramètres

```typescript
// Dans le fichier de traduction
{
  "messages": {
    "welcome": "Bienvenue {{name}}, vous avez {{count}} messages"
  }
}

// Dans le composant
const message = t('messages.welcome', { 
  name: 'Alice', 
  count: 5 
});
// Résultat: "Bienvenue Alice, vous avez 5 messages"
```

### Formatage des Données

```typescript
const { formatDate, formatNumber, formatCurrency } = useLocalization();

// Formatage de date selon la locale
const dateFormatted = formatDate(new Date()); // "07/01/2026" (fr)

// Formatage de nombre
const numberFormatted = formatNumber(1234.56); // "1 234,56" (fr)

// Formatage de devise
const priceFormatted = formatCurrency(99.99); // "99,99 €" (fr)
```

## 📝 Structure des Traductions

### Organisation Hiérarchique

```json
{
  "realDemo": {
    "title": "Démonstration Réelle",
    "status": {
      "connected": "Connecté",
      "disconnected": "Déconnecté"
    },
    "messages": {
      "actionExecuted": "Action exécutée"
    }
  },
  "common": {
    "loading": "Chargement...",
    "error": "Erreur"
  }
}
```

### Conventions de Nommage

- **Modules** : `realDemo`, `dashboard`, `workflow`
- **Catégories** : `status`, `messages`, `actions`
- **Clés** : `camelCase` pour la cohérence
- **Valeurs** : Texte naturel avec majuscules appropriées

## 🔧 Ajout d'une Nouvelle Langue

### 1. Mettre à Jour la Configuration

```json
// i18n/config.json
{
  "supportedLanguages": [
    // ... langues existantes
    {
      "code": "it",
      "name": "Italiano",
      "flag": "🇮🇹",
      "dateFormat": "DD/MM/YYYY",
      "timeFormat": "HH:mm",
      "currency": "EUR",
      "currencySymbol": "€",
      "decimalSeparator": ",",
      "thousandsSeparator": "."
    }
  ]
}
```

### 2. Créer le Fichier de Traductions

```bash
# Copier un fichier existant comme base
cp i18n/fr.json i18n/it.json

# Traduire le contenu
# Respecter la structure JSON existante
```

### 3. Mettre à Jour le Service

```typescript
// Dans LocalizationService.ts
private getLocaleString(): string {
  const localeMap: { [key: string]: string } = {
    'fr': 'fr-FR',
    'en': 'en-US',
    'es': 'es-ES',
    'de': 'de-DE',
    'it': 'it-IT'  // Ajouter la nouvelle langue
  };
  
  return localeMap[this.currentLanguage] || 'fr-FR';
}
```

## 🎨 Intégration avec le Design System

### Sélecteur de Langue

```typescript
import LanguageSelector from '../LanguageSelector';

// Variantes disponibles
<LanguageSelector variant="button" showFlag={true} showName={true} />
<LanguageSelector variant="chip" size="small" />
<LanguageSelector variant="menu" />
```

### Styles Cohérents

Le sélecteur de langue suit le design system RPA Vision V3 :

- **Couleurs** : Palette sombre (`#1e293b`, `#334155`)
- **Typographie** : Material-UI par défaut
- **Espacement** : Tokens du design system
- **Responsive** : Adaptation mobile automatique

## 🧪 Tests et Validation

### Test de Changement de Langue

```typescript
// Test manuel
const testLanguageChange = async () => {
  const { changeLanguage, getCurrentLanguage, t } = useLocalization();
  
  console.log('Langue actuelle:', getCurrentLanguage());
  
  await changeLanguage('en');
  console.log('Nouvelle langue:', getCurrentLanguage());
  console.log('Traduction test:', t('common.loading'));
};
```

### Validation des Traductions

```bash
# Vérifier la structure JSON
node -e "console.log(JSON.parse(require('fs').readFileSync('i18n/fr.json')))"

# Comparer les clés entre langues
diff <(jq -r 'paths(scalars) as $p | $p | join(".")' i18n/fr.json | sort) \
     <(jq -r 'paths(scalars) as $p | $p | join(".")' i18n/en.json | sort)
```

## 📱 Responsive et Accessibilité

### Adaptation Mobile

```css
@media (max-width: 768px) {
  .language-selector-button {
    min-width: auto;
    padding: 6px 12px;
  }
  
  .language-flag {
    font-size: 1em;
  }
}
```

### Accessibilité

- **ARIA labels** : Ajoutés automatiquement
- **Navigation clavier** : Support complet
- **Contraste** : Respecte les standards WCAG
- **Screen readers** : Compatible

## 🔄 Synchronisation et Persistance

### Sauvegarde Automatique

```typescript
// La langue choisie est sauvegardée automatiquement
localStorage.setItem('rpa-vision-language', langCode);

// Restauration au démarrage
const savedLang = localStorage.getItem('rpa-vision-language');
```

### Détection Automatique

```typescript
// Détection de la langue du navigateur
const browserLang = navigator.language.split('-')[0];
// Exemple: "fr-FR" → "fr"
```

## 🚨 Gestion d'Erreurs

### Fallback Automatique

1. **Traduction manquante** → Langue de fallback (français)
2. **Fichier manquant** → Langue par défaut
3. **Erreur de chargement** → Affichage de la clé

### Messages d'Erreur

```typescript
// Logs automatiques pour le debugging
console.warn(`Traduction manquante pour la clé: ${key} (langue: ${currentLanguage})`);
console.error(`Erreur lors du chargement des traductions pour ${langCode}:`, error);
```

## 📊 Performance

### Optimisations

- **Chargement à la demande** : Seules les langues utilisées sont chargées
- **Cache en mémoire** : Traductions mises en cache
- **Singleton pattern** : Une seule instance du service
- **Listeners efficaces** : Gestion optimisée des événements

### Métriques

```typescript
// Temps de chargement des traductions
console.time('loadTranslations');
await loadTranslations(langCode);
console.timeEnd('loadTranslations');
```

## 🔮 Évolutions Futures

### Fonctionnalités Prévues

1. **Traduction automatique** : Intégration d'APIs de traduction
2. **Pluralisation** : Gestion des formes plurielles
3. **Contexte dynamique** : Traductions selon le contexte
4. **Validation automatique** : Vérification de cohérence

### Extensibilité

```typescript
// Interface pour futures extensions
interface TranslationPlugin {
  name: string;
  process(key: string, value: string, context?: any): string;
}
```

## 📚 Ressources

### Documentation Technique

- **Material-UI i18n** : https://mui.com/guides/localization/
- **React i18n patterns** : Bonnes pratiques communautaires
- **Intl API** : APIs natives du navigateur

### Outils Utiles

```bash
# Validation JSON
jq . i18n/fr.json

# Extraction de clés
grep -r "t('" src/ | cut -d"'" -f2 | sort | uniq

# Comparaison de fichiers
diff i18n/fr.json i18n/en.json
```

---

**🌍 Le système de localisation RPA Vision V3 est conçu pour une expérience utilisateur internationale de qualité !**

Ce guide assure une implémentation cohérente et maintenable du système multilingue, respectant les standards internationaux et les bonnes pratiques de développement.