useLingo

useLingo() es la forma en que los componentes acceden al runtime. Lee el <LingoProvider> más cercano y devuelve el objeto Lingo activo. Llámalo una vez por componente, conserva la referencia y usa los métodos que necesites.

tsx

import { useLingo } from "@lingo.dev/react";

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}

Lanza una excepción si se llama fuera de un provider, así que en los tests debes envolver el renderizado, incluso con messages: {} si las traducciones no importan en esa prueba.

`l.text(source, options)` — cadenas simples#

La llamada de cada día. Devuelve una cadena traducida o el original si no existe traducción para el idioma actual.

tsx

l.text("Save", { context: "Form button" });
// → "Speichern" (de) / "Save" (en, fallback)

Interpolación#

Los segmentos {placeholder} se sustituyen a partir de options.values.

tsx

l.text("Welcome back, {name}!", {
  values: { name: user.firstName },
  context: "Dashboard greeting",
});

Los valores que faltan se renderizan literalmente como {name}, algo muy útil para detectar errores durante el desarrollo. Eso sí, asegúrate de que tus tests validen el resultado renderizado para que no se cuelen valores vacíos.

Cuando el original contiene sintaxis ICU#

Si la cadena original incluye marcadores de plural / select / number / date, el runtime se adapta automáticamente; no necesitas ninguna API adicional. Consulta Plurals and select para ver el envoltorio más sencillo.

`l.rich(source, options)` — subárboles de React#

Cuando el texto traducido incluye componentes de React (enlaces, negrita, un <Icon/>), usa l.rich. La cadena de traducción lleva etiquetas de marcador de posición como <link>...</link>; asigna cada etiqueta a un renderizador.

tsx

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 autocerradas también funcionan:

tsx

l.rich("Loading <spinner/>...", {
  tags: { spinner: () => <Spinner /> },
  context: "Inline loading state",
});

Las etiquetas sin renderizador recurren al texto sin procesar, así que la ausencia de una etiqueta se ve 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 neutros (<link>) en lugar de <a href="...">, que tendrían que conservar literalmente y a menudo acaban rompiendo. 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 a partir de `Intl.Locale.textInfo` + la lista de idiomas RTL de respaldo.
`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 tomar decisiones de diseño:

tsx

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 envoltorios ligeros sobre los formateadores nativos de Intl.*, ajustados a l.locale.

Fuera de React#

useLingo solo funciona dentro de componentes. Para utilidades, cargadores de rutas o código de servidor, crea directamente el mismo objeto:

import { createLingo } from "@lingo.dev/react";

const l = createLingo("es", messages);
l.text("Hello", { context: "Email subject" });

Tiene la misma forma que Lingo, sin necesidad de provider. LingoProvider usa createLingo por debajo.

tsx

import { useLingo } from "@lingo.dev/react";

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}