LingoProvider

LingoProvider es el contexto de React que almacena el idioma activo y el mapa de mensajes. Envuélvelo una sola vez en la raíz de tu aplicación y todo lo que quede dentro podrá llamar a useLingo() para traducir cadenas o consultar 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 se pueden anidar. 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 los bundles por ruta sin renunciar a un conjunto común de traducciones "shell" en la raíz.

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>

Muy útil para renderizar un único componente en un idioma fijo (una cita, una inserción, un panel de vista previa) dentro de una aplicación que, por lo demás, usa otro idioma.

Cambiar de idioma en tiempo de ejecución#

Trata locale como estado de React: cámbialo y todos los consumidores de useLingo() que haya debajo se volverán 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(), incluye:

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

Resultan útiles para diseños condicionales (como reflejar iconos en RTL) o para etiquetado analítico, sin necesidad de análisis adicionales.

Errores habituales#

• Olvidar <LingoProvider>. useLingo() lanza un error si se usa fuera de uno. El mensaje te indica que añadas un proveedor; si te ocurre en tests, envuelve el renderizado en un proveedor de prueba con messages vacío para que las comprobaciones 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 después pasa el resultado hacia abajo.
• Cambiar locale sin actualizar messages. El proveedor asume que ambas props van juntas: cámbialas en la misma actualización de useState o, si no, durante un instante renderizarás el nuevo idioma con las traducciones antiguas.