useLingo

useLingo() é a forma como os componentes acedem ao runtime. Lê o <LingoProvider> mais próximo e devolve o objeto Lingo ativo — chame-o uma vez por componente, guarde a referência e use os métodos de que precisar.

tsx

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

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

Gera uma exceção se for chamado fora de um provider, por isso os testes precisam de envolver o render — mesmo com messages: {}, se as traduções não forem relevantes para o teste.

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

A chamada do dia a dia. Devolve uma string traduzida ou, se não existir tradução para o idioma atual, a string de origem.

tsx

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

Interpolação#

Os segmentos {placeholder} são substituídos com valores de options.values.

tsx

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

Os valores em falta são renderizados literalmente como {name} — útil para detetar erros durante o desenvolvimento, mas garanta que os testes validam o resultado renderizado para que valores vazios não passem despercebidos.

Quando a origem contém sintaxe ICU#

Se a string de origem contiver marcadores de plural / select / number / date, o runtime adapta-se automaticamente — sem API adicional. Consulte Plurals and select para a abstração mais simples.

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

Quando o texto traduzido inclui componentes React (ligações, negrito, um <Icon/>), use l.rich. A string de tradução transporta etiquetas placeholder como <link>...</link>; basta mapear cada etiqueta para um renderer.

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</>

As etiquetas self-closing também funcionam:

tsx

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

As etiquetas sem renderer recorrem ao texto em bruto por defeito — assim, a ausência da etiqueta fica visível em desenvolvimento, em vez de passar despercebida.

Não coloque markup diretamente dentro de strings traduzidas. l.rich existe para que os tradutores vejam placeholders neutros (<link>) em vez de <a href="...">, que teriam de preservar literalmente e que muitas vezes acabam por quebrar. Defina o renderer no código, não no ficheiro de idioma.

Metadados do idioma em `l`#

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

Propriedade	Tipo	Notas
`l.locale`	`string`	O valor que passou a `LingoProvider`. BCP-47.
`l.direction`	`"ltr"` \| `"rtl"`	Calculado com base em `Intl.Locale.textInfo` + lista de fallback de idiomas RTL.
`l.script`	`string` \| `undefined`	Inferido sempre que possível (`"Latn"`, `"Cyrl"`, `"Arab"`, …).
`l.region`	`string` \| `undefined`	Inferido a partir de 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 — consulte Formatting para a descrição completa. São wrappers leves sobre os formatadores nativos Intl.*, configurados para l.locale.

Fora do React#

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

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

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

Tem a mesma estrutura de Lingo, sem precisar de provider. O próprio LingoProvider usa createLingo internamente.

tsx

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

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