LingoProvider

LingoProvider est le contexte React qui stocke la langue active et la table des messages. Enveloppez-le une seule fois à la racine de votre application — tout ce qu’il contient peut ensuite appeler useLingo() pour traduire des chaînes ou lire les métadonnées de langue.

Utilisation de base#

import { LingoProvider } from "@lingo.dev/react";
import messages from "./locales/es.json";

<LingoProvider locale="es" messages={messages}>
  <App />
</LingoProvider>

Props#

Messages n’est rien d’autre que Record<string, string> — exactement le même format que le CLI écrit dans locales/<locale>.json.

Imbriquer des providers#

Les providers peuvent être imbriqués. Les règles diffèrent selon que le provider imbriqué utilise la même langue que le parent ou une langue différente.

Même langue — les messages fusionnent#

<LingoProvider locale="es" messages={sharedMessages}>
  {/* Route-scoped messages override shared on collision; missing keys fall through to shared. */}
  <LingoProvider locale="es" messages={dashboardMessages}>
    <Dashboard />
  </LingoProvider>
</LingoProvider>

Pratique pour découper les bundles par route tout en conservant à la racine un ensemble commun de traductions pour le "shell".

Langues différentes — autonome#

<LingoProvider locale="es" messages={esMessages}>
  <Header />
  <LingoProvider locale="ar-SA" messages={arMessages}>
    {/* This subtree is entirely Arabic; the parent's es messages are NOT visible. */}
    <ArabicEmbed />
  </LingoProvider>
</LingoProvider>

Idéal pour afficher un composant isolé dans une langue fixe (une citation, une intégration, un panneau d’aperçu) au sein d’une application dans une autre langue.

Changer de langue à l’exécution#

Traitez locale comme un état React — modifiez-le, et tous les composants qui consomment useLingo() en dessous se re-rendront avec la nouvelle langue et le nouveau lot de messages.

function AppRoot() {
  const [locale, setLocale] = useState("en");
  const [messages, setMessages] = useState({});

  async function switchTo(next: string) {
    const next_messages = await import(`./locales/${next}.json`);
    setLocale(next);
    setMessages(next_messages.default);
  }

  return (
    <LingoProvider locale={locale} messages={messages}>
      <LocaleSwitcher current={locale} onSelect={switchTo} />
      <App />
    </LingoProvider>
  );
}

Ce que vous pouvez lire depuis le contexte#

useLingo() renvoie l’objet Lingo actif. En plus de text() et rich(), il inclut :

• locale — la chaîne BCP-47 que vous avez passée
• direction — "ltr" ou "rtl", calculé via Intl.Locale.textInfo avec une liste de repli de langues RTL connues
• script — par ex. "Latn", "Cyrl", "Arab"
• region — par ex. "US", "DE", "SA"

Ces informations sont utiles pour adapter la mise en page de façon conditionnelle (par exemple inverser les icônes en RTL) ou pour le marquage analytique — sans parsing supplémentaire.

Erreurs fréquentes#

• Oublier <LingoProvider>. useLingo() lève une erreur en dehors d’un provider. Le message d’erreur vous indique d’en ajouter un ; si cela arrive dans vos tests, enveloppez le rendu dans un provider de test avec des messages vides pour garder des assertions stables.
• Passer directement des messages chargés de façon asynchrone. messages doit recevoir une valeur synchrone. Résolvez la promesse dans un parent (avec Suspense ou un état), puis passez le résultat.
• Changer locale sans mettre à jour messages. Le provider considère ces deux props comme indissociables — mettez-les à jour dans le même update useState, sinon vous afficherez brièvement la nouvelle langue avec les anciennes traductions.