# Système de Localisation - RPA Vision V3

> **Support multilingue pour l'interface utilisateur**  
> Auteur : Dom, Alice, Kiro - 7 janvier 2026

## 🌍 Langues Supportées

| Langue | Code | Statut | Fichier |
|--------|------|--------|---------|
| 🇫🇷 Français | `fr` | ✅ Complet | `fr.json` |
| 🇺🇸 English | `en` | ✅ Complet | `en.json` |
| 🇪🇸 Español | `es` | ✅ Complet | `es.json` |
| 🇩🇪 Deutsch | `de` | ✅ Complet | `de.json` |

## 📁 Structure des Fichiers

```
i18n/
├── config.json              # Configuration des langues
├── fr.json                  # Traductions françaises (référence)
├── en.json                  # Traductions anglaises
├── es.json                  # Traductions espagnoles
├── de.json                  # Traductions allemandes
├── validate_translations.py # Script de validation
└── README.md               # Ce fichier
```

## 🚀 Utilisation Rapide

### Dans un Composant React

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

const MonComposant = () => {
  const { t, changeLanguage } = useLocalization();
  
  return (
    <div>
      <h1>{t('realDemo.title')}</h1>
      <button onClick={() => changeLanguage('en')}>
        Switch to English
      </button>
    </div>
  );
};
```

### Clés de Traduction Principales

```typescript
// Démonstration réelle
t('realDemo.title')                    // "Démonstration Réelle"
t('realDemo.status.connected')         // "Connecté"
t('realDemo.controls.createWorkflow')  // "Créer Workflow de Démo"

// Interface commune
t('common.loading')                    // "Chargement..."
t('common.save')                      // "Sauvegarder"
t('common.cancel')                    // "Annuler"

// Temps et unités
t('time.seconds')                     // "secondes"
t('units.pixels')                     // "pixels"
```

## 🔧 Validation

### Script de Validation Automatique

```bash
# Valider toutes les traductions
python validate_translations.py

# Exemple de sortie
✅ Chargé: fr.json
✅ Chargé: en.json  
✅ Chargé: es.json
✅ Chargé: de.json
📋 Clés de référence (fr): 127
🔍 en: 127 clés (0 manquantes, 0 supplémentaires)
🔍 es: 127 clés (0 manquantes, 0 supplémentaires)
🔍 de: 127 clés (0 manquantes, 0 supplémentaires)

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

### Validation Manuelle

```bash
# Vérifier la syntaxe JSON
python -m json.tool fr.json > /dev/null && echo "✅ fr.json valide"

# Compter les clés
jq 'paths(scalars) | length' fr.json

# Comparer les structures
diff <(jq -r 'paths(scalars) as $p | $p | join(".")' fr.json | sort) \
     <(jq -r 'paths(scalars) as $p | $p | join(".")' en.json | sort)
```

## 📝 Conventions

### Nommage des Clés

- **Modules** : `realDemo`, `dashboard`, `workflow`
- **Catégories** : `status`, `messages`, `actions`, `controls`
- **Format** : `camelCase` pour la cohérence
- **Hiérarchie** : Maximum 3 niveaux de profondeur

### Format des Valeurs

```json
{
  "simple": "Texte simple",
  "withParams": "Bonjour {{name}}, vous avez {{count}} messages",
  "multiline": "Première ligne\nSeconde ligne",
  "withHtml": "Texte avec <strong>mise en forme</strong>"
}
```

### Paramètres Dynamiques

```typescript
// Utilisation des paramètres
t('messages.welcome', { name: 'Alice', count: 5 })
// Résultat: "Bienvenue Alice, vous avez 5 messages"
```

## 🌐 Configuration des Locales

### Formats par Langue

| Langue | Date | Heure | Devise | Décimal | Milliers |
|--------|------|-------|--------|---------|----------|
| 🇫🇷 fr | DD/MM/YYYY | HH:mm | EUR (€) | , | espace |
| 🇺🇸 en | MM/DD/YYYY | h:mm A | USD ($) | . | , |
| 🇪🇸 es | DD/MM/YYYY | HH:mm | EUR (€) | , | . |
| 🇩🇪 de | DD.MM.YYYY | HH:mm | EUR (€) | , | . |

### Exemples de Formatage

```typescript
// Date: 7 janvier 2026
formatDate(date)
// fr: "07/01/2026"
// en: "01/07/2026"  
// de: "07.01.2026"

// Nombre: 1234.56
formatNumber(1234.56)
// fr: "1 234,56"
// en: "1,234.56"
// de: "1.234,56"

// Devise: 99.99
formatCurrency(99.99)
// fr: "99,99 €"
// en: "$99.99"
// de: "99,99 €"
```

## 🔄 Ajout d'une Nouvelle Langue

### 1. Configuration

```json
// Ajouter dans config.json
{
  "code": "it",
  "name": "Italiano", 
  "flag": "🇮🇹",
  "dateFormat": "DD/MM/YYYY",
  "timeFormat": "HH:mm",
  "currency": "EUR",
  "currencySymbol": "€",
  "decimalSeparator": ",",
  "thousandsSeparator": "."
}
```

### 2. Fichier de Traduction

```bash
# Copier la structure française
cp fr.json it.json

# Traduire le contenu en gardant la structure JSON
# Respecter les placeholders {{param}}
```

### 3. Validation

```bash
# Valider la nouvelle langue
python validate_translations.py

# Vérifier l'intégration
# Tester dans l'interface utilisateur
```

## 🎯 Bonnes Pratiques

### Pour les Traducteurs

1. **Contexte** : Comprendre le contexte d'utilisation
2. **Cohérence** : Utiliser les mêmes termes pour les mêmes concepts
3. **Longueur** : Adapter la longueur selon l'espace disponible
4. **Culture** : Respecter les conventions culturelles

### Pour les Développeurs

1. **Clés descriptives** : Utiliser des noms de clés explicites
2. **Paramètres** : Préférer les paramètres aux concaténations
3. **Pluralisation** : Gérer les formes plurielles si nécessaire
4. **Fallback** : Toujours prévoir une langue de secours

## 🐛 Dépannage

### Problèmes Courants

#### Traduction Non Affichée

```typescript
// Vérifier la clé
console.log(t('ma.cle.inexistante')); // Affiche la clé si non trouvée

// Vérifier la langue actuelle
console.log(getCurrentLanguage());

// Vérifier le chargement
console.log(localizationService.translations);
```

#### Fichier JSON Invalide

```bash
# Valider la syntaxe
python -m json.tool problematic.json

# Erreurs communes:
# - Virgule en trop
# - Guillemets manquants
# - Caractères d'échappement incorrects
```

#### Clés Manquantes

```bash
# Identifier les clés manquantes
python validate_translations.py

# Comparer avec la référence
diff fr.json en.json
```

## 📊 Statistiques Actuelles

- **Total des clés** : 156 traductions (+3 nouvelles clés pour RealDemo)
- **Couverture** : 100% pour toutes les langues
- **Modules couverts** : 
  - Démonstration réelle (`realDemo`) - **ÉTENDU**
  - Interface commune (`common`)
  - Temps et unités (`time`, `units`)

## 🔮 Évolutions Prévues

- **Pluralisation** : Gestion des formes plurielles
- **Contexte dynamique** : Traductions selon le contexte
- **Traduction automatique** : Assistance IA pour nouvelles langues
- **Validation continue** : Intégration dans le CI/CD

---

**🌍 Le système de localisation RPA Vision V3 assure une expérience utilisateur internationale de qualité !**