useLingo() es la forma en que los componentes acceden al runtime. Lee el <LingoProvider> más cercano y devuelve el objeto activo Lingo: llámalo una vez por componente, conserva la referencia y usa los métodos que necesites.
import { useLingo } from "@lingo.dev/react";
function Greeting() {
const l = useLingo();
return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}Lanza un error si se llama fuera de un provider, así que en tus tests tienes que envolver el renderizado, incluso con messages: {} si las traducciones no importan en esa prueba.
l.text(source, options) — cadenas simples#
La llamada de todos los días. Devuelve una cadena traducida o, si no existe traducción para el idioma actual, el texto original.
l.text("Save", { context: "Form button" });
// → "Speichern" (de) / "Save" (en, fallback)Interpolación#
Los segmentos {placeholder} se sustituyen a partir de options.values.
l.text("Welcome back, {name}!", {
values: { name: user.firstName },
context: "Dashboard greeting",
});Los valores faltantes se renderizan literalmente como {name}; esto viene bien para detectar errores durante el desarrollo, pero asegúrate de que tus tests validen el resultado renderizado para que no se cuelen valores vacíos.
Cuando el texto original contiene sintaxis ICU#
Si la cadena original contiene marcadores de plural / select / número / fecha, el runtime se actualiza automáticamente; no necesitas una API adicional. Consulta Plurals and select para ver la envoltura más práctica.
l.rich(source, options) — subárboles de React#
Cuando el texto traducido contiene componentes de React (enlaces, texto en negrita, un <Icon/>), usa l.rich. La cadena de traducción incluye etiquetas de marcador de posición como <link>...</link>; tú asignas cada etiqueta a un renderizador.
l.rich("Click <link>here</link> for {topic}", {
tags: {
link: (children) => <a href="/help">{children}</a>,
},
values: { topic: "details" },
context: "Footer help link",
});
// → <>Click <a href="/help">here</a> for details</>Las etiquetas autocontenidas también funcionan:
l.rich("Loading <spinner/>...", {
tags: { spinner: () => <Spinner /> },
context: "Inline loading state",
});Las etiquetas sin renderizador vuelven al texto sin procesar, así que la ausencia de una etiqueta se nota en desarrollo y no se omite silenciosamente.
No pongas marcado directamente dentro de las cadenas traducidas. l.rich existe para que los traductores vean marcadores de posición neutros (<link>) en lugar de <a href="...">, que tendrían que conservar tal cual y suelen romper. Define el renderizador en tu código, no en el archivo de idioma.
Metadatos del idioma en l#
Además de traducir, el objeto expone:
| Propiedad | Tipo | Notas |
|---|---|---|
l.locale | string | Lo que hayas pasado a LingoProvider. BCP-47. |
l.direction | "ltr" | "rtl" | Se calcula con Intl.Locale.textInfo + una lista de respaldo de idiomas RTL. |
l.script | string | undefined | Se infiere cuando es posible ("Latn", "Cyrl", "Arab", …). |
l.region | string | undefined | Se infiere a partir de BCP-47 ("US", "DE", "SA", …). |
Útil para decisiones de diseño:
const l = useLingo();
return <div dir={l.direction}>...</div>;Métodos de formato#
l también incluye num, currency, percent, date, time, datetime, relative, list, displayName, sort, segment, fileSize, compact, unit; consulta Formatting para ver el desglose completo. Son envolturas ligeras sobre los formateadores nativos de Intl.*, ajustados según l.locale.
Fuera de React#
useLingo solo funciona dentro de componentes. Para utilidades, cargadores de rutas o código del servidor, crea directamente ese mismo objeto:
import { createLingo } from "@lingo.dev/react";
const l = createLingo("es", messages);
l.text("Hello", { context: "Email subject" });Tiene la misma estructura que Lingo; no necesitas ningún provider. LingoProvider usa createLingo internamente.
