Expert I18n
Vue d'ensemble
Livrer une configuration i18n complète + un audit : configurer le framework i18n, remplacer les chaînes visibles par l'utilisateur par des clés, assurer la parité entre les locales, et valider les pluriels et le formatage pour en-US et zh-CN.
Capacités principales
- Sélection et configuration de bibliothèques (React, Next.js, Vue).
- Architecture des clés et organisation des fichiers de locale.
- Génération de traductions et stratégie de qualité (IA, professionnelle, manuelle).
- Routage et détection/changement de langue.
- Localisation SEO et des métadonnées (le cas échéant).
- Support RTL (uniquement si les locales RTL sont dans le périmètre).
Entrées de périmètre (demander si ambigu)
- Framework et style de routage.
- État i18n existant (aucun, partiel, hérité).
- Locales cibles (par défaut : en-US + zh-CN).
- Besoins en qualité de traduction (IA vs professionnelle vs manuelle).
- Formats de locale utilisés (JSON, YAML, PO, XLIFF).
- Exigences de formalité/culturelles (le cas échéant).
Workflow (Auditer → Corriger → Valider)
- Confirmer le périmètre et les locales cibles
- Identifier le framework i18n et les emplacements des fichiers de locale.
- Confirmer les locales ; par défaut en-US + zh-CN lorsqu'elles sont spécifiées.
- Configurer la base i18n (si manquante)
- Choisir une bibliothèque adaptée au framework (ex. React : react-i18next ; Next.js : next-intl ; Vue : vue-i18n).
- Installer les packages et créer le fichier d'entrée/configuration i18n.
- Connecter le fournisseur (provider) à la racine de l'application et charger les ressources de locale.
- Ajouter un sélecteur de langue et la persistance (route/param/localStorage) selon le besoin.
- Établir la structure des fichiers de locale et les espaces de noms.
- Si le routage est sensible à la locale, définir tôt la stratégie de segment de locale (sous-chemin, sous-domaine, paramètre de requête).
- Si les métadonnées sont visibles par l'utilisateur, inclure la traduction des titres/descriptions.
- Auditer l'utilisation des clés et la parité des locales
- Exécuter :
python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json> - Traiter les clés manquantes/les écarts de parité comme des bloqueurs.
- Vérifier manuellement les clés dynamiques (
t(var)).
- Trouver les chaînes brutes visibles par l'utilisateur
- Rechercher :
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<" rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\"" - Localiser les libellés d'accessibilité.
- Remplacer les chaînes par des clés
- Utiliser
t('espace_de_noms.clé')pour le texte d'interface. - Pour les pluriels, utiliser
t('clé', { count })+ les clés_one/_other. - Utiliser les formatteurs Intl/application pour les dates, heures et nombres.
- Localiser la gestion des erreurs (critique)
- Mapper les codes d'erreur à des clés localisées ; n'afficher que l'interface localisée.
- Journaliser les détails bruts de l'erreur uniquement.
- Fournir une solution de repli localisée pour les codes inconnus.
- Mettre à jour les fichiers de locale
- Ajouter les clés manquantes dans les deux locales.
- Rester cohérent avec les espaces réservés ; éviter les renommages sauf demande explicite.
- Générer les traductions selon la méthode convenue ; préserver les espaces réservés et les règles de pluriel.
- Valider
- Relancer l'audit jusqu'à ce qu'il n'y ait plus de clés manquantes ni d'écarts.
- Valider le JSON (ex.
python -m json.tool <fichier>). - Mettre à jour les tests qui vérifient le texte visible.
Garde-fous
- Ne jamais exposer
error.messagebrut dans l'interface ; n'afficher que des chaînes localisées. - Ne pas ajouter de locales supplémentaires sauf demande explicite.
- Privilégier les espaces de noms structurés (ex.
errors.*,buttons.*,workspace.*). - Garder les traductions concises et cohérentes.
- Certains termes techniques/marques doivent rester non traduits (ex. nom du produit, API, MCP, Bash).
Livrables (sorties attendues)
- Configuration/fournisseur i18n.
- Fichiers de locale pour chaque langue cible.
- Chaînes d'interface remplacées par des clés stables.
- Sélecteur de langue et persistance (le cas échéant).
- Tests mis à jour pour le texte visible.
Directives d'architecture (garder concises)
- Structure des clés : privilégier les espaces de noms imbriqués par zone (ex.
common.buttons.save,pricing.tier.pro). - Organisation des fichiers : un fichier par locale ou des espaces de noms par locale ; maintenir la synchronisation des clés entre les locales.
- Espaces réservés : préserver exactement
{nom}/{{nom}}; valider les pluriels selon les règles de la locale. - Formatage : utiliser les aides Intl/application pour le formatage des dates, heures, nombres et listes.
- SEO/métadonnées : localiser les titres et descriptions si l'application les expose.
- RTL : uniquement nécessaire pour les locales RTL ; utiliser les propriétés CSS logiques et tester la mise en page.
- Les surfaces non-web (boîtes de dialogue du processus principal Electron, invites CLI, menus natifs) nécessitent également une localisation.
Notes de performance (courtes)
- Charger paresseusement les bundles de locale lorsque l'application le supporte.
- Diviser les gros fichiers de locale par espace de noms.
Modes d'échec (liste de surveillance)
- Traductions manquantes : revenir à la locale par défaut et journaliser les avertissements.
- Problèmes de mise en page RTL : vérifier le CSS logique et tester les pages.
- SEO manquant : s'assurer que les alternatives et métadonnées sont localisées le cas échéant.
Liste de validation (courte)
- Aucune clé manquante et aucune chaîne brute dans l'interface.
- Le changement de locale fonctionne et persiste.
- Pluriels et formatage vérifiés dans les deux locales.
- Locale de repli configurée.
Ressources
scripts/
scripts/i18n_audit.py: Extrait l'utilisation det('clé')et compare avec les fichiers JSON de locale.
Déclencheurs d'activation
Mapper les codes d'erreur à des messages localisés, et valider la parité des clés, les pluriels et le formatage.