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 entrada del 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 de entrada.
Estos ejemplos de renderizado requieren React 19. Sigue las instrucciones de instalación de la guía de inicio rápido de React antes de usar el proveedor.
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>, no una ruta de archivo, una promesa ni una lista de entradas JSONC analizadas. La carga del catálogo genera este mapa.
Datos de entrada del proveedor #
| Propiedad | Contrato |
|---|---|
locale | Cadena obligatoria que se utiliza para los diagnósticos de búsqueda de mensajes, la gramática y el formato. |
messages | Mapa opcional de cadenas con claves hash; el valor predeterminado es {}. |
children | Subárbol ReactNode obligatorio. |
Incluso con un catálogo vacío, el subárbol dispone de formato adaptado al idioma; las llamadas a mensajes utilizan sus plantillas de origen. El proveedor no establece por sí mismo el idioma ni la dirección del documento.
Llama a useLingo desde un componente situado bajo el proveedor. Si lo llamas fuera de un proveedor, se lanza una excepción. Devolver un proveedor desde el mismo componente no sitúa el hook de ese componente bajo é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 fusionan sus mapas. Las entradas del proveedor hijo sustituyen a las del padre con claves coincidentes, mientras que las demás entradas del padre siguen disponibles. Así, una ruta puede añadir mensajes específicos de la página sin repetir los mensajes de navegación compartidos.
<LingoProvider locale="fr" messages={sharedMessages}>
<LingoProvider locale="fr" messages={pageMessages}>
<SettingsPage />
</LingoProvider>
</LingoProvider>Aquí, sharedMessages y pageMessages son mapas en francés ya cargados. Si el idioma del proveedor interno cambia a es, este pasa a ser independiente: cuando falta un mensaje en español, se utiliza el texto de origen en lugar del texto en francés. La comparación se basa en la cadena literal del idioma, así que escribe los identificadores de idioma de forma coherente en toda la aplicación.
Cambia el idioma y el catálogo a la vez #
Guarda los datos de entrada del renderizado como un par, por ejemplo, { locale: "fr", messages: frenchMessages }. Carga el siguiente mapa y sustituye el par en una única actualización de estado. Si cambias solo el idioma, puede seguir mostrándose texto en francés con el formato numérico del 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, sigue la guía correspondiente de Next Pages o TanStack; sus selectores cargan los nuevos datos de entrada de forma distinta.
Crea un objeto Lingo sin un hook #
Usa createLingo(locale: string, messages?: Messages): Lingo cuando una función necesite una cadena fuera de un componente de React:
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 da 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 los atributos del documento y conserva los mismos datos de entrada durante la hidratación.