rpa_vision_v3/visual_workflow_builder/GUIDE_LOCALISATION.md

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)

{
  "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

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

// 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

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

{
  "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

// 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

# 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

// 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

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

// 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

# 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

@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

// 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

// 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

// 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

// 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é

// 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

# 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.