Migrer les messages React existants
Passez un petit jeu de test de messages React à des messages explicitement définis par leur texte source et leur contexte, sans perdre les espaces réservés, le comportement des pluriels ni les traductions acceptées.
Un catalogue React existant reflète déjà des choix utiles : identifiants de recherche, règles d’interpolation, comportement des pluriels et traductions ayant fait l’objet d’une relecture. Le passage à des messages définis par leur texte source et leur contexte doit préserver ce travail. Convertissez d’abord un composant complet, associez ses traductions acceptées aux nouveaux identifiants, puis comparez son rendu avant d’étendre la migration.
Consigner le comportement existant avant de changer les identifiants #
Choisissez un composant comportant un libellé, une variable, un lien, un nombre et un message conditionnel. Consignez ses anciennes clés, ses formulations source et cible, sa syntaxe d’interpolation, son espace de noms et la langue de son fournisseur. Affichez-le dans la langue source et dans une langue cible avec des valeurs fixes. Vous disposerez ainsi d’un résultat concret à préserver pendant la migration.
Par exemple, un appel existant de type i18next pourrait se présenter ainsi :
t("account.greeting", { name });Son catalogue source pourrait contenir Welcome, {{name}}. Ne reprenez pas cette syntaxe d’interpolation telle quelle dans un nouveau contrat de message. Le message React explicite utilise une variable nommée {name} :
l.text("Welcome, {name}", {
context: "Greeting on the signed-in account page",
values: { name },
});Le changement de délimiteurs présenté ici est propre à cette configuration de la bibliothèque source. Vérifiez la bibliothèque installée avant de convertir d’autres messages : des délimiteurs d’interpolation personnalisés et des conventions de pluriel peuvent nécessiter des modifications différentes.
Faire correspondre le comportement des messages, pas seulement les noms de méthodes #
Utilisez text pour les messages simples contenant des valeurs, rich pour les emplacements de composants nommés, plural pour les formes qui dépendent d’un nombre et select pour les variantes correspondant à des valeurs exactes, avec une solution de repli other. Messages interactifs enrichis propose un exemple complet de ces quatre possibilités.
Un ancien composant de message enrichi peut encoder les liens par indice. Remplacez ces indices par des emplacements dont les noms sont explicites et conservez la destination du lien dans le code. Préservez les noms, les types et les rôles sémantiques des variables. Un ancien catalogue de pluriels peut stocker des clés à suffixe ; le nouveau moteur d’exécution construit le message au pluriel à partir de ses différentes formes. Vérifiez le comportement de la langue cible plutôt que de renommer mécaniquement les clés à suffixe.
Choisissez un contexte qui explique l’usage du message. Le nouvel identifiant repose sur la formulation source et le contexte, plutôt que sur account.greeting. Tenez un tableau de migration indiquant l’ancienne clé, la langue, la nouvelle clé extraite et les éventuelles conversions de syntaxe. Pour le message de salutation, la ligne correspondante consigne la conversion de {{name}} en {name}. Cette table permet à la personne chargée de la relecture de retrouver les formulations acceptées dans le nouveau catalogue et de repérer les messages encore sans correspondance.
Extraire et importer un petit catalogue avec soin #
Installez @lingo.dev/react et configurez LingoProvider en suivant le guide de démarrage rapide React. Utilisez React 19 pour l’implémentation actuelle du fournisseur ; la plage de compatibilité React 18 déclarée dans ses dépendances homologues ne dispense pas de tester une application plus ancienne. Après avoir converti le composant, exécutez la CLI installée :
lingo extract --src src --source-locale enSi vous n’avez pas redéfini les chemins, examinez locales/en.jsonc et lingo.d.ts. Retrouvez chaque message source et son contexte, puis copiez la clé effectivement extraite dans le tableau de migration. Conserver l’ancienne clé ou inventer un hachage romprait le lien entre la traduction cible et la recherche effectuée à l’exécution.
Placez chaque traduction cible acceptée sous la nouvelle clé qui lui correspond. Convertissez avec soin la syntaxe des espaces réservés, des emplacements enrichis et des pluriels, tout en préservant le sens. Chargez une table associant les hachages aux chaînes via le workflow de chargement des catalogues, en utilisant les clés actives de la source correspondante lorsque les métadonnées cibles sont absentes. Laissez les entrées sans correspondance visibles parmi le travail restant, plutôt que de les classer comme obsolètes.
Fournissez ensemble la langue demandée et ses messages cibles à LingoProvider. Pendant la migration progressive, conservez l’ancien et le nouveau fournisseur autour de leurs appelants respectifs. Le contrat du fournisseur explique la fusion pour une même langue et l’isolation entre langues différentes ; vérifiez ces comportements lors de la migration d’un écran imbriqué.
Vérifier les messages manquants ou mal formés #
Affichez le jeu de test avec les mêmes valeurs qu’avant la migration. Comparez le sens du texte affiché, le placement des variables, le comportement des liens, le rendu des pluriels et le choix de la solution de repli. Testez les nombres zéro, un et des nombres plus élevés, des valeurs de variables longues et une valeur de sélection inconnue.
Supprimez une entrée cible dans un jeu de test local et vérifiez le repli sur le texte source. Les messages manquants ou vides peuvent afficher le texte source : un écran utilisable ne prouve donc pas que la couverture des traductions cibles est complète. Exécutez les contrôles de cohérence de l’extraction et les vérifications TypeScript en incluant les déclarations générées, puis lancez les tests de rendu existants de l’application. Les types garantissent la compatibilité des appels, pas la qualité des traductions.
Pour une balise enrichie ou un message ICU mal formé, examinez le résultat et les diagnostics. Le nouveau moteur d’exécution peut laisser apparaître le balisage tel quel ou un modèle non formaté ; confrontez donc ce comportement aux exigences de l’application avant de supprimer l’ancien moteur d’exécution. Le guide de dépannage React décrit ces limites.
Soumettre le travail assisté par un agent à une relecture #
Demandez à l’agent d’examiner la bibliothèque existante, de conserver une table de correspondance des clés, de repérer les schémas non pris en charge et de séparer les modifications du code source de l’importation du catalogue. Relisez les modifications qu’il propose pour le code source et le catalogue avant de les appliquer.
Étendez la migration par composant ou par espace de noms une fois que le jeu de test a réussi les contrôles de rendu et les vérifications natives. Conservez les deux catalogues jusqu’à ce que chaque appelant et chaque traduction cible acceptée aient une destination vérifiée. Ne supprimez l’ancien fournisseur et l’ancienne dépendance que lorsqu’aucun code ne les utilise plus. Les clients API et les adaptateurs de routage ont des responsabilités distinctes ; changer le moteur d’exécution des messages ne les remplace pas.