Proveedor y hooks

Proporciona un idioma y un catálogo, combina mensajes compartidos y específicos de cada página, y cambia de idioma sin mezclar los datos de renderizado.

LingoProvider pone un idioma y un catálogo a disposición de un subárbol de componentes. useLingo() lee el proveedor más cercano y devuelve los métodos de mensajes y formato correspondientes a esos datos.

Estos ejemplos de renderizado requieren React 19. Sigue los pasos de instalación de la guía de inicio rápido de React antes de usar el proveedor.

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

Carga los mensajes en francés antes de renderizar Settings. El proveedor acepta Messages, un Record<string, string>, en lugar de una ruta de archivo, una promesa o una lista de entradas JSONC ya analizadas. La carga del catálogo genera este mapa.

Datos de entrada del proveedor #

PropiedadContrato
localeCadena obligatoria que se usa para los diagnósticos de búsqueda de mensajes, la gramática y el formato.
messagesMapa opcional de cadenas con claves hash; su valor predeterminado es {}.
childrenSubárbol ReactNode obligatorio.

Incluso con un catálogo vacío, el subárbol puede aplicar formatos según el idioma; las llamadas a mensajes usan sus plantillas de origen. El proveedor en sí no establece el idioma ni la dirección del documento.

Llama a useLingo desde un componente ubicado debajo del proveedor. Si lo llamas fuera de un proveedor, se lanza una excepción. Devolver un proveedor desde ese mismo componente no coloca el hook del componente debajo de él, así que separa el contenedor del proveedor del componente que lee el hook.

Combina mensajes compartidos y específicos de cada página #

Los proveedores anidados con la misma cadena de idioma combinan sus mapas. Las entradas del proveedor hijo reemplazan las entradas del proveedor padre con claves coincidentes, mientras que las demás entradas del padre siguen disponibles. Así, una ruta puede agregar mensajes específicos de una página sin repetir los mensajes de navegación compartidos.

tsx
<LingoProvider locale="fr" messages={sharedMessages}>
  <LingoProvider locale="fr" messages={pageMessages}>
    <SettingsPage />
  </LingoProvider>
</LingoProvider>

Aquí, sharedMessages y pageMessages son mapas en francés que ya están cargados. Si el idioma del proveedor interno cambia a es, ese proveedor se vuelve independiente: cuando falta un mensaje en español, se usa el texto de origen como alternativa, en lugar de recurrir al texto en francés. La comparación usa la cadena literal del idioma, así que escribe los identificadores de idioma de forma consistente en toda la aplicación.

Cambia el idioma y el catálogo al mismo tiempo #

Guarda los datos de renderizado como un par, por ejemplo, { locale: "fr", messages: frenchMessages }. Carga el siguiente mapa y luego reemplaza el par en una sola actualización de estado. Si cambias solo el idioma, puede seguir apareciendo texto en francés con formato numérico en español.

Mientras se carga el siguiente catálogo, mantén visible el par anterior o muestra un estado de carga, según el diseño de interacción de la aplicación. En aplicaciones con enrutamiento, usa la guía correspondiente de Next Pages o TanStack; sus selectores de idioma cargan los nuevos datos de distintas maneras.

Crea un objeto Lingo sin usar un hook #

Usa createLingo(locale: string, messages?: Messages): Lingo cuando una función necesite una cadena fuera de un componente de React:

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

Esto devuelve Account settings y aplica formato a la proporción como 12.5% en este idioma. No realiza ninguna solicitud de traducción ni se suscribe a un proveedor. Crea un objeto nuevo cuando cambien el idioma o los mensajes.

Tanto createLingo como useLingo exponen locale, direction, script y region. Usa los metadatos del idioma para aplicar atributos al documento y conserva los mismos datos de entrada durante la hidratación.