Fournisseur et hooks
Fournissez une langue et un catalogue, combinez les messages partagés et ceux des pages, et changez de langue sans mélanger les données d’entrée du rendu.
LingoProvider met une langue et un catalogue à la disposition d’un sous-arbre de composants. useLingo() lit le fournisseur le plus proche et renvoie les méthodes de gestion des messages et de formatage correspondant à ces données d’entrée.
Ces exemples de rendu nécessitent React 19. Suivez les instructions d’installation du guide de démarrage rapide React avant d’utiliser le fournisseur.
import { LingoProvider, useLingo, type Messages } from "@lingo.dev/react";
function SaveButton() {
const l = useLingo();
return (
<button type="submit">
{l.text("Save", { context: "Submit changes to account settings" })}
</button>
);
}
export function Settings({ messages }: { messages: Messages }) {
return (
<LingoProvider locale="fr" messages={messages}>
<SaveButton />
</LingoProvider>
);
}Chargez les messages en français avant d’effectuer le rendu de Settings. Le fournisseur accepte Messages, de type Record<string, string>, et non un chemin de fichier, une promesse ou une liste d’entrées JSONC analysées. Le chargement du catalogue produit cette table.
Données d’entrée du fournisseur #
| Propriété | Contrat |
|---|---|
locale | Chaîne obligatoire utilisée pour les diagnostics de recherche des messages, la grammaire et le formatage. |
messages | Table de chaînes facultative dont les clés sont des empreintes de hachage ; vaut {} par défaut. |
children | Sous-arbre ReactNode obligatoire. |
Même avec un catalogue vide, le sous-arbre bénéficie d’un formatage adapté à la langue ; les appels de messages utilisent leurs modèles sources. Le fournisseur lui-même ne définit ni la langue ni le sens d’écriture du document.
Appelez useLingo dans un composant situé sous le fournisseur. Un appel en dehors d’un fournisseur lève une exception. Renvoyer un fournisseur depuis ce même composant ne place pas son hook sous le fournisseur : séparez donc le composant qui sert d’enveloppe au fournisseur de celui qui utilise le hook.
Combiner les messages partagés et ceux des pages #
Les fournisseurs imbriqués ayant la même chaîne de langue fusionnent leurs tables. Les entrées du fournisseur enfant remplacent celles du parent dont les clés correspondent, tandis que les autres entrées du parent restent disponibles. Une route peut ainsi ajouter les messages d’une page sans répéter les messages de navigation partagés.
<LingoProvider locale="fr" messages={sharedMessages}>
<LingoProvider locale="fr" messages={pageMessages}>
<SettingsPage />
</LingoProvider>
</LingoProvider>Ici, sharedMessages et pageMessages sont des tables de messages en français déjà chargées. Si la langue du fournisseur interne passe à es, celui-ci devient indépendant : les messages espagnols manquants utilisent le texte source comme solution de repli, au lieu de reprendre le texte français. La comparaison porte sur la chaîne de langue exacte : veillez donc à l’écrire de manière cohérente dans toute l’application.
Changer la langue et le catalogue ensemble #
Stockez les données d’entrée du rendu sous forme de paire, par exemple { locale: "fr", messages: frenchMessages }. Chargez la table suivante, puis remplacez la paire en une seule mise à jour d’état. Si vous changez uniquement la langue, du texte français peut rester affiché avec des nombres au format espagnol.
Pendant le chargement du catalogue suivant, continuez à afficher le contenu avec la paire précédente ou affichez un état de chargement, selon les interactions prévues dans l’application. Dans les applications avec routage, suivez la recette Next Pages ou TanStack correspondante ; leurs sélecteurs de langue chargent les nouvelles données d’entrée différemment.
Créer un objet Lingo sans hook #
Utilisez createLingo(locale: string, messages?: Messages): Lingo lorsqu’une fonction a besoin d’une chaîne en dehors d’un composant React :
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en-US");
const title = l.text("Account settings", { context: "Settings page title" });
const percentage = l.percent(0.125, { maximumFractionDigits: 1 });Cet appel renvoie Account settings et formate le ratio sous la forme 12.5% dans cette langue. Il n’envoie aucune requête de traduction et ne s’abonne à aucun fournisseur. Créez un nouvel objet lorsque la langue ou les messages changent.
createLingo et useLingo exposent tous deux locale, direction, script et region. Utilisez les métadonnées de langue pour appliquer les attributs du document, et conservez les mêmes données d’entrée pendant l’hydratation.