useLingo(), c’est ainsi que les composants accèdent au runtime. Il lit le <LingoProvider> le plus proche et renvoie l’objet Lingo actif — appelez-le une fois par composant, conservez la référence et utilisez les méthodes dont vous avez besoin.
import { useLingo } from "@lingo.dev/react";
function Greeting() {
const l = useLingo();
return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}Il génère une erreur s’il est appelé en dehors d’un provider ; en test, il faut donc envelopper le rendu — même avec messages: {} si les traductions n’ont pas d’importance dans ce cas.
l.text(source, options) — chaînes simples#
L’appel le plus courant. Renvoie une chaîne traduite, ou la source si aucune traduction n’existe pour la langue actuelle.
l.text("Save", { context: "Form button" });
// → "Speichern" (de) / "Save" (en, fallback)Interpolation#
Les segments {placeholder} sont remplacés à partir de options.values.
l.text("Welcome back, {name}!", {
values: { name: user.firstName },
context: "Dashboard greeting",
});Les valeurs manquantes s’affichent littéralement sous la forme {name} — pratique pour repérer les bugs en développement, mais veillez à ce que vos tests valident le rendu final pour éviter que des valeurs vides ne passent entre les mailles du filet.
Quand la source contient de la syntaxe ICU#
Si la chaîne source contient des marqueurs de pluriel / select / nombre / date, le runtime monte automatiquement en puissance — aucune API supplémentaire. Voir Pluriels et select pour le wrapper plus simple à utiliser.
l.rich(source, options) — sous-arbres React#
Quand le texte traduit contient des composants React (liens, texte en gras, un <Icon/>), utilisez l.rich. La chaîne de traduction contient des balises d’espace réservé comme <link>...</link> ; vous associez chaque balise à une fonction de rendu.
l.rich("Click <link>here</link> for {topic}", {
tags: {
link: (children) => <a href="/help">{children}</a>,
},
values: { topic: "details" },
context: "Footer help link",
});
// → <>Click <a href="/help">here</a> for details</>Les balises autofermantes fonctionnent aussi :
l.rich("Loading <spinner/>...", {
tags: { spinner: () => <Spinner /> },
context: "Inline loading state",
});Les balises sans fonction de rendu retombent sur le texte brut — ainsi, l’absence de balise reste visible en développement au lieu d’être silencieusement ignorée.
N’insérez pas de balisage directement dans les chaînes traduites. l.rich existe pour que les traducteurs voient des espaces réservés neutres (<link>) plutôt que <a href="...">, qu’ils devraient sinon conserver à l’identique et qu’ils cassent souvent. Définissez la fonction de rendu dans votre code, pas dans le fichier de langue.
Métadonnées de langue sur l#
Au-delà de la traduction, l’objet expose aussi :
| Propriété | Type | Notes |
|---|---|---|
l.locale | string | La valeur transmise à LingoProvider. BCP-47. |
l.direction | "ltr" | "rtl" | Calculé via Intl.Locale.textInfo + une liste de secours des langues RTL. |
l.script | string | undefined | Déduit lorsque c’est possible ("Latn", "Cyrl", "Arab", …). |
l.region | string | undefined | Déduit à partir du BCP-47 ("US", "DE", "SA", …). |
Pratique pour les choix de mise en page :
const l = useLingo();
return <div dir={l.direction}>...</div>;Méthodes de formatage#
l expose aussi num, currency, percent, date, time, datetime, relative, list, displayName, sort, segment, fileSize, compact, unit — voir Formatting pour le détail complet. Ce sont de simples wrappers autour des formateurs natifs Intl.*, calés sur l.locale.
En dehors de React#
useLingo fonctionne uniquement dans les composants. Pour les utilitaires, les chargeurs de routes ou le code serveur, construisez directement le même objet :
import { createLingo } from "@lingo.dev/react";
const l = createLingo("es", messages);
l.text("Hello", { context: "Email subject" });C’est la même structure Lingo, sans provider. LingoProvider lui-même s’appuie sur createLingo en interne.
