Localiser des messages interactifs enrichis
Traduisez une phrase complète tout en laissant le code React contrôler ses liens, composants et valeurs.
« Lisez la politique avant de continuer » reste une seule phrase, même lorsque « politique » est un lien. Traduire la phrase en un seul bloc permet de placer le lien au bon endroit dans une autre langue, tout en laissant le code de l’application contrôler sa destination.
La méthode rich du package React représente ce lien par un emplacement nommé. Le catalogue fournit la phrase ; un moteur de rendu React fournit le composant associé à cet emplacement.
Afficher une phrase complète contenant un lien #
Installez @lingo.dev/react dans une application React 19 existante. Cet exemple local utilise un catalogue espagnol à titre d’illustration et ne nécessite aucune requête de traduction :
npm install @lingo.dev/reactimport { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";
const messages = {
[computeKey(
"Read the <policy>policy</policy> before continuing.",
"Notice before account creation",
)]: "Antes de continuar, lee la <policy>política</policy>.",
};
function ConsentNotice() {
const l = useLingo();
return (
<p>
{l.rich("Read the <policy>policy</policy> before continuing.", {
context: "Notice before account creation",
tags: {
policy: (children) => <a href="/policy">{children}</a>,
},
})}
</p>
);
}
export function App() {
return (
<LingoProvider locale="es" messages={messages}>
<ConsentNotice />
</LingoProvider>
);
}Le paragraphe doit afficher « Antes de continuar, lee la política. » La phrase traduite déplace la référence à la politique, mais le lien pointe toujours vers /policy. Le texte source littéral et le contexte fournis dans l’appel permettent aussi de reconnaître le message lors de l’extraction. computeKey construit l’identité réelle du jeu de données de test plutôt que de s’appuyer sur une empreinte inventée.
Le fournisseur utilise actuellement la syntaxe de contexte de React 19, bien que le package déclare React 18 et 19 comme dépendances homologues. Vérifiez séparément la compatibilité avec React 18. Le guide de démarrage rapide React explique comment configurer le fournisseur et le premier catalogue.
Conserver les valeurs et le comportement dans le code #
Le nom policy identifie un emplacement, et non un élément HTML fourni lors de la traduction. Son moteur de rendu contrôle la destination et le comportement. Déterminez la destination propre à chaque langue à partir d’une table de correspondance de routes connue dans le code ; laissez les gestionnaires d’événements et les attributs HTML arbitraires hors du catalogue.
Pour les valeurs variables, utilisez des paramètres de substitution nommés :
const greeting = l.text("Welcome, {name}", {
context: "Greeting on the signed-in account page",
values: { name },
});
const countLabel = l.plural(
count,
{ one: "# item", other: "# items" },
{ context: "Number of items in the cart" },
);
const roleLabel = l.select(
role,
{ admin: "Administrator", other: "Member" },
{ context: "Account role label" },
);Ces appels doivent se trouver dans un composant disposant de const l = useLingo() et des valeurs de l’application pour name, count et role. text renvoie du texte brut, plural détermine la forme grammaticale selon le nombre et select établit une correspondance exacte avec un sélecteur, avec other comme solution de repli. Le traitement du texte enrichi prend en charge les balises nommées et l’interpolation simple de valeurs ; il n’exécute pas le formateur ICU complexe utilisé pour le texte brut. Consultez pluriels, dates et nombres pour gérer ces choix à l’exécution.
Gardez le texte source statique. Insérer le nom d’une personne dans la chaîne source créerait un texte différent pour chaque personne et empêcherait une extraction fiable. Le contexte doit préciser l’usage, par exemple « Libellé du rôle du compte », car le texte source et le contexte déterminent ensemble l’identité du message. Une fois les traductions créées, ne modifiez le contexte que de manière délibérée.
Remplacer le jeu de données de test local par des catalogues extraits #
Une fois la version actuelle de la CLI installée, exécutez :
lingo extract --src src --source-locale enSi vous ne modifiez pas les chemins par défaut, cette commande écrit locales/en.jsonc et lingo.d.ts. Examinez le texte source, le contexte et la clé extraits. Incluez la déclaration dans la configuration TypeScript de l’application. L’extraction prend en charge les appels de messages reconnaissables ; elle ne détecte pas les chaînes sources arbitraires générées dynamiquement.
Suivez le guide de démarrage rapide de la CLI pour vous authentifier et associer un moteur de localisation, puis sélectionnez cette source locales/en.jsonc réelle et les langues cibles requises dans .lingo/config.json. Traduisez et récupérez le catalogue en suivant ce workflow de fichiers. Utilisez la procédure de chargement des catalogues pour analyser le JSONC, sélectionner les clés actives de la révision source correspondante et transmettre les chaînes cibles au fournisseur. L’outil général de traduction de fichiers ne conserve pas les commentaires du catalogue source dans les fichiers cibles.
Chargez le même avis avec le catalogue espagnol récupéré. Les entrées absentes ou vides se rabattent sur le texte source : comparez donc les clés cibles requises, mais aussi le résultat visible.
Tester l’interaction et les messages mal formés #
Suivez le lien vers la politique au clavier et vérifiez son nom accessible. Lisez la ponctuation autour du lien après son déplacement. Une traduction complète doit préserver à la fois le sens de la phrase et l’action proposée à la personne qui la lit.
Dans un catalogue local de test, supprimez le gestionnaire de balise, ajoutez une balise inconnue et laissez une balise non fermée. Le moteur de rendu actuel laisse les balises inconnues ou non appariées sous forme de texte ; l’appariement des balises imbriquées de même nom est limité. Ce n’est ni un moteur capable de rendre du HTML arbitraire, ni un validateur qui rejette tous les messages mal formés.
Pour le texte brut, vérifiez les valeurs manquantes et les messages ICU complexes mal formés : les paramètres de substitution non résolus ou le modèle non formaté peuvent rester visibles, avec des diagnostics en développement. Pour les messages liés au nombre et au rôle, testez les catégories de pluriel de la langue cible ainsi qu’un rôle inconnu. Consultez la référence du texte enrichi et les conseils de test React pour connaître le comportement exact associé à ces vérifications.