useLingo

useLingo() é como os componentes acessam o runtime. Ele lê o <LingoProvider> mais próximo e retorna o objeto Lingo ativo — chame uma vez por componente, mantenha a referência e use os métodos que precisar.

tsx

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

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

Ele gera erro se for chamado fora de um provider, então os setups de teste precisam envolver a renderização — até com messages: {} se as traduções não forem importantes para o teste.

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

A chamada do dia a dia. Retorna uma string traduzida ou a original, caso não exista tradução para o idioma atual.

tsx

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

Interpolação#

Os segmentos {placeholder} são substituídos com base em options.values.

tsx

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

Valores ausentes são renderizados literalmente como {name} — ótimo para identificar bugs durante o desenvolvimento, mas garanta que seus testes validem o resultado renderizado para que valores vazios não passem batido.

Quando a string de origem contém sintaxe ICU#

Se a string de origem contiver marcadores de plural / select / número / data, o runtime faz o upgrade automaticamente — sem API extra. Veja Plurais e select para a versão mais amigável.

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

Quando o texto traduzido inclui componentes React (links, negrito, um <Icon/>), use l.rich. A string de tradução leva tags placeholder como <link>...</link>; você mapeia cada tag para um 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</>

Tags autocontidas também funcionam:

tsx

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

Tags sem renderizador recorrem ao texto bruto — assim, a ausência da tag fica visível no desenvolvimento, em vez de passar despercebida.

Não coloque marcação diretamente dentro de strings traduzidas. l.rich existe para que tradutores vejam placeholders neutros (<link>) em vez de <a href="...">, que precisariam ser preservados literalmente e costumam quebrar. Defina o renderizador no seu código, não no arquivo de idioma.

Metadados de idioma em `l`#

Além da tradução, o objeto expõe:

Propriedade	Tipo	Observações
`l.locale`	`string`	Tudo o que você passou para `LingoProvider`. BCP-47.
`l.direction`	`"ltr"` \| `"rtl"`	Calculado via `Intl.Locale.textInfo` + lista de fallback de idiomas RTL.
`l.script`	`string` \| `undefined`	Inferido quando possível (`"Latn"`, `"Cyrl"`, `"Arab"`, …).
`l.region`	`string` \| `undefined`	Inferido a partir do BCP-47 (`"US"`, `"DE"`, `"SA"`, …).

Útil para decisões de layout:

tsx

const l = useLingo();
return <div dir={l.direction}>...</div>;

Métodos de formatação#

l também inclui num, currency, percent, date, time, datetime, relative, list, displayName, sort, segment, fileSize, compact, unit — veja Formatting para a visão completa. São wrappers leves em torno dos formatadores nativos Intl.*, configurados para l.locale.

Fora do React#

useLingo só funciona dentro de componentes. Para utilitários, loaders de rota ou código de servidor, crie o mesmo objeto diretamente:

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

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

É o mesmo formato de Lingo, sem precisar de provider. O próprio LingoProvider usa createLingo por baixo dos panos.

tsx

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

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