LingoProvider

LingoProvider é o contexto do React que guarda o idioma ativo e o mapa de mensagens. Envolva-o uma única vez na raiz da sua aplicação — tudo o que estiver dentro pode chamar useLingo() para traduzir strings ou ler metadados do idioma.

Utilização básica#

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> — a mesma estrutura que o CLI escreve em locales/<locale>.json.

Providers aninhados#

Os providers podem ser aninhados. As regras mudam consoante o provider aninhado tenha o mesmo idioma do provider pai ou um diferente.

Mesmo idioma — as mensagens são combinadas#

<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 isto para dividir bundles por rota, mantendo ao mesmo tempo 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 apresentar um único componente num idioma fixo (uma citação, um embed, um painel de pré-visualização) dentro de uma aplicação que, de resto, está noutro idioma.

Mudar de idioma em tempo de execução#

Trate locale como estado do React — altere-o e todos os consumidores de useLingo() abaixo voltam a renderizar 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 pode ler a partir do contexto#

useLingo() devolve o objeto Lingo ativo. Para além de text() e rich(), inclui:

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

Isto é útil para layouts condicionais (espelhar ícones em RTL) ou etiquetagem analítica — sem necessidade de parsing adicional.

Erros comuns#

• Esquecer-se de <LingoProvider>. useLingo() gera um erro fora de um provider. A mensagem de erro diz-lhe para adicionar um provider; se estiver a ver isto em testes, envolva o render num provider em modo de teste com messages vazio para manter as asserções estáveis.
• Passar diretamente mensagens carregadas de forma assíncrona. messages tem de ser um valor síncrono. Resolva a promise num componente pai (com Suspense ou estado) e depois passe o resultado.
• Mudar locale sem atualizar messages. O provider assume as duas props em conjunto — altere-as na mesma atualização de useState ou, durante um breve momento, irá renderizar o novo idioma com as traduções antigas.