LingoProvider

LingoProvider é o contexto do React que mantém o idioma ativo e o mapa de mensagens. Envolva a raiz do seu app com ele uma vez — tudo lá dentro pode chamar useLingo() para traduzir strings ou acessar metadados do idioma.

Uso básico#

import { LingoProvider } from "@lingo.dev/react";
import messages from "./locales/es.json";

<LingoProvider locale="es" messages={messages}>
  <App />
</LingoProvider>

Props#

Messages é simplesmente Record<string, string> — o mesmo formato que o CLI grava em locales/<locale>.json.

Providers aninhados#

Providers podem ser aninhados. As regras mudam conforme o provider interno use o mesmo idioma do provider pai ou um idioma diferente.

Mesmo idioma — as mensagens se mesclam#

<LingoProvider locale="es" messages={sharedMessages}>
  {/* Route-scoped messages override shared on collision; missing keys fall through to shared. */}
  <LingoProvider locale="es" messages={dashboardMessages}>
    <Dashboard />
  </LingoProvider>
</LingoProvider>

Use isso para dividir bundles por rota e manter um conjunto comum de traduções de "shell" na raiz.

Idiomas diferentes — independente#

<LingoProvider locale="es" messages={esMessages}>
  <Header />
  <LingoProvider locale="ar-SA" messages={arMessages}>
    {/* This subtree is entirely Arabic; the parent's es messages are NOT visible. */}
    <ArabicEmbed />
  </LingoProvider>
</LingoProvider>

Útil para renderizar um único componente em um idioma fixo (uma citação, um embed, um painel de prévia) dentro de um app que, no restante, usa outro idioma.

Troca de idioma em tempo de execução#

Trate locale como estado do React — ao alterá-lo, todo consumidor de useLingo() abaixo dele é renderizado novamente com o novo idioma e o novo conjunto de mensagens.

function AppRoot() {
  const [locale, setLocale] = useState("en");
  const [messages, setMessages] = useState({});

  async function switchTo(next: string) {
    const next_messages = await import(`./locales/${next}.json`);
    setLocale(next);
    setMessages(next_messages.default);
  }

  return (
    <LingoProvider locale={locale} messages={messages}>
      <LocaleSwitcher current={locale} onSelect={switchTo} />
      <App />
    </LingoProvider>
  );
}

O que você pode ler do contexto#

useLingo() retorna o objeto Lingo ativo. Além de text() e rich(), ele também traz:

• locale — a string BCP-47 que você informou
• direction — "ltr" ou "rtl", calculado via Intl.Locale.textInfo com uma lista de fallback de idiomas RTL conhecidos
• script — por exemplo "Latn", "Cyrl", "Arab"
• region — por exemplo "US", "DE", "SA"

Esses dados são úteis para layouts condicionais (como espelhar ícones em RTL) ou marcação em analytics — sem precisar de parsing extra.

Erros comuns#

• Esquecer <LingoProvider>. useLingo() gera erro fora dele. A própria mensagem de erro orienta você a adicionar um provider; se isso aparecer nos testes, envolva a renderização em um provider de teste com messages vazio para manter as asserções estáveis.
• Passar mensagens carregadas de forma assíncrona diretamente. messages precisa ser um valor síncrono. Resolva a promise em um componente pai (com Suspense ou estado) e só então passe o resultado adiante.
• Trocar locale sem atualizar messages. O provider pressupõe que essas duas props andem juntas — atualize ambas na mesma mudança de useState, ou o app vai renderizar por instantes o novo idioma com as traduções antigas.