Résoudre les problèmes de messages React

Repérez à quel moment un message perd sa traduction, ses valeurs, ses balises ou sa langue entre l’extraction et le rendu.

Suivez le message effectivement affiché à l’écran. Son texte source et son contexte déterminent une clé ; le fournisseur le plus proche fournit le catalogue ; le modèle sélectionné est mis en forme avec les valeurs de l’appel. Examiner ces données permet généralement de trouver l’origine du problème sans modifier manuellement les clés générées.

useLingo lève une exception en dehors d’un fournisseur #

Placez LingoProvider au-dessus du composant qui appelle le hook, y compris dans les tests et les aperçus isolés. Un fournisseur renvoyé par ce même composant se trouve en dessous du hook. Déplacez le hook dans un composant enfant ou utilisez createLingo(locale, messages) dans une fonction dont le rendu ne passe pas par le contexte React.

Utilisez React 19 avec l’implémentation actuelle du fournisseur. La syntaxe abrégée du contexte React 19 qu’elle utilise n’est pas compatible avec React 18, même si le paquet déclare une plage de versions plus large pour ses dépendances homologues.

Le texte source s’affiche à la place de la traduction #

  1. Vérifiez les valeurs effectives de locale et messages du fournisseur le plus proche. Les messages doivent être une table associant des empreintes à des chaînes, et non une URL de fichier, une promesse ou LocaleFile.
  2. Calculez computeKey(source, context) à partir de l’appel exact. Recherchez cette clé dans la table fournie. Toute modification de la ponctuation, des espaces ou du contexte peut créer une nouvelle identité.
  3. Si la clé est absente de l’extraction, utilisez un texte source et un contexte littéraux avec un récepteur pris en charge, tel que l.text(...), puis relancez l’extraction. Un appel calculé peut produire un rendu à l’exécution sans pouvoir être extrait.
  4. Si le catalogue source contient la clé, mais pas le catalogue cible, récupérez la traduction terminée et rechargez la table. Le simple envoi ne suffit pas à placer le fichier dans l’application.
  5. Si le fichier contient la clé, mais pas le fournisseur, vérifiez les chemins du chargeur et la sélection de la route. Chargement des catalogues décrit la jointure sur les clés sources nécessaire lorsque le JSONC traduit a perdu ses métadonnées.

Les valeurs manquantes comme les chaînes vides déclenchent un repli sur le texte source. Les avertissements de développement distinguent ces deux cas et sont dédupliqués par clé et par langue. En production, ces diagnostics sont désactivés : une console vide ne garantit donc pas que le catalogue est complet.

Le chargeur Next renvoie {} lorsqu’un fichier manque, mais peut lever une exception si le JSONC est mal formé. Le catalogue intégré de TanStack intercepte les erreurs liées aux fichiers manquants, au chargement et à l’analyse, renvoie {} et met ce résultat en cache. Dans les deux cas, le repli sur le texte source peut garder la page lisible tout en masquant un problème de chargement.

Une variable de substitution ou une expression ICU reste visible #

Vérifiez l’objet values transmis à l’appel. Si des valeurs simples manquent, {name} reste visible. Sans objet de valeurs, le moteur d’exécution renvoie le modèle sélectionné sans le mettre en forme.

Pour un message ICU complexe, vérifiez la syntaxe, les noms d’arguments et les types de valeurs de la traduction cible sélectionnée. En cas d’erreur d’analyse ou de mise en forme, le moteur renvoie ce même modèle et émet une erreur de développement dédupliquée. Une traduction mal formée peut donc s’afficher à la place du texte source anglais. Corrigez le modèle ou fournissez l’argument manquant, puis testez à nouveau le rendu de ce cas.

Les déclarations générées permettent de détecter les erreurs liées aux arguments repérés dans la source, mais elles ne valident pas la syntaxe cible et ne repèrent pas toutes les variables de substitution imbriquées dans une branche ICU. Testez la branche concernée avec des valeurs réelles.

Les messages enrichis utilisent des fonctions de rappel nommées telles que tags.link. Respectez exactement le nom de la balise traduite et conservez sa destination dans la fonction de rappel. Les paires de balises inconnues, les balises autofermantes et les balises ouvrantes non refermées restent du texte littéral.

Utilisez des noms distincts pour les éléments imbriqués. L’imbrication répétée de balises portant le même nom n’est pas prise en charge par l’analyseur. Les messages enrichis prennent en charge les variables de substitution simples, mais pas la grammaire ICU complète ; utilisez les fonctions utilitaires de grammaire textuelle pour cela. Texte enrichi présente les formes prises en charge.

L’URL change, mais pas la langue #

Remplacez la langue et le catalogue en même temps. Une mise à jour de la langue seule peut mettre en forme du texte français selon les règles espagnoles. Vérifiez aussi les fournisseurs imbriqués : un fournisseur enfant utilisant une autre langue est indépendant et n’hérite pas du catalogue du parent.

Suivez le mécanisme de changement de langue de l’adaptateur sélectionné. Next Pages utilise la navigation du routeur et un cookie de langue. TanStack utilise de simples liens pour qu’une nouvelle requête puisse charger le nouveau catalogue.

Le texte, le sens d’écriture ou les dates changent pendant l’hydratation #

Comparez les données côté serveur et côté client : révision du catalogue, langue, valeurs, horodatage, fuseau horaire et référence pour les temps relatifs. Définissez lang et dir du document dans la structure principale du framework ; le fournisseur de base ne les modifie pas. Testez ensuite le HTML initial et la page hydratée à l’aide de la liste de vérification du rendu côté serveur.