LingoProvider

LingoProvider es el contexto de React que guarda el idioma activo y el mapa de mensajes. Envuélvelo una sola vez en la raíz de tu app: todo lo que esté dentro puede llamar a useLingo() para traducir textos o leer metadatos del idioma.

Uso básico#

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

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

Props#

Messages no es más que Record<string, string>: la misma estructura que el CLI escribe en locales/<locale>.json.

Proveedores anidados#

Los proveedores pueden anidarse. Las reglas cambian según si el proveedor anidado tiene el mismo idioma que el padre o uno distinto.

Mismo idioma — los mensajes se combinan#

<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>

Úsalo para dividir bundles por ruta mientras mantienes en la raíz un conjunto común de traducciones para el "shell".

Idiomas distintos — independientes#

<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>

Es ideal para renderizar un solo componente en un idioma fijo (una cita, un embed, un panel de vista previa) dentro de una app que, por lo demás, usa otro idioma.

Cambiar el idioma en tiempo de ejecución#

Trata locale como estado de React: cámbialo y cada consumidor de useLingo() que esté debajo se volverá a renderizar con el nuevo idioma y el nuevo conjunto de mensajes.

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>
  );
}

Qué puedes leer del contexto#

useLingo() devuelve el objeto Lingo activo. Además de text() y rich(), también incluye:

• locale — la cadena BCP-47 que pasaste
• direction — "ltr" o "rtl", calculado con Intl.Locale.textInfo y una lista de respaldo de idiomas RTL conocidos
• script — por ejemplo "Latn", "Cyrl", "Arab"
• region — por ejemplo "US", "DE", "SA"

Esto sirve para ajustar el layout de forma condicional (como reflejar íconos en RTL) o para etiquetar analítica, sin necesidad de parsing adicional.

Errores comunes#

• Olvidar <LingoProvider>. useLingo() lanza un error fuera de uno. El mensaje te indica que agregues un proveedor; si lo ves en pruebas, envuelve el render en un proveedor de test con messages vacío para que las aserciones sean estables.
• Pasar directamente mensajes cargados de forma asíncrona. messages debe ser un valor síncrono. Resuelve la promesa en un componente padre (con Suspense o estado) y luego pasa el resultado hacia abajo.
• Cambiar locale sin actualizar messages. El proveedor da por hecho que ambas props van juntas: cámbialas en la misma actualización de useState o, si no, renderizarás brevemente el nuevo idioma con las traducciones anteriores.