Provedor e hooks

Forneça um idioma e um catálogo, combine mensagens compartilhadas com as de cada página e troque de idioma sem misturar as entradas de renderização.

LingoProvider disponibiliza um idioma e um catálogo para uma subárvore de componentes. useLingo() lê o provedor mais próximo e retorna os métodos de mensagens e formatação correspondentes a essas entradas.

Estes exemplos de renderização exigem React 19. Siga as instruções de instalação do guia de início rápido do React antes de usar o provedor.

tsx
import { LingoProvider, useLingo, type Messages } from "@lingo.dev/react";

function SaveButton() {
  const l = useLingo();
  return (
    <button type="submit">
      {l.text("Save", { context: "Submit changes to account settings" })}
    </button>
  );
}

export function Settings({ messages }: { messages: Messages }) {
  return (
    <LingoProvider locale="fr" messages={messages}>
      <SaveButton />
    </LingoProvider>
  );
}

Carregue as mensagens em francês antes de renderizar Settings. O provedor aceita Messages, um Record<string, string>, e não um caminho de arquivo, uma promise ou uma lista de entradas JSONC já analisada. O carregamento do catálogo gera esse mapa.

Entradas do provedor #

PropriedadeContrato
localeString obrigatória usada nos diagnósticos de busca de mensagens, na gramática e na formatação.
messagesMapa opcional de strings com hashes como chaves; o padrão é {}.
childrenSubárvore de ReactNode obrigatória.

Mesmo com um catálogo vazio, a subárvore conta com formatação adequada ao idioma; as chamadas de mensagens usam seus modelos de origem. O provedor, por si só, não define o idioma nem a direção do documento.

Chame useLingo em um componente abaixo do provedor. A chamada fora de um provedor lança uma exceção. Retornar um provedor no mesmo componente não coloca o hook desse componente abaixo dele. Por isso, separe o componente que encapsula o conteúdo no provedor daquele que lê o hook.

Combine mensagens compartilhadas com as de cada página #

Provedores aninhados com a mesma string de idioma mesclam seus mapas. As entradas do provedor filho substituem as que têm chaves correspondentes no provedor pai, enquanto as demais entradas do pai continuam disponíveis. Assim, uma rota pode adicionar mensagens de página sem repetir as mensagens de navegação compartilhadas.

tsx
<LingoProvider locale="fr" messages={sharedMessages}>
  <LingoProvider locale="fr" messages={pageMessages}>
    <SettingsPage />
  </LingoProvider>
</LingoProvider>

Aqui, sharedMessages e pageMessages são mapas em francês já carregados. Se o idioma do provedor interno mudar para es, esse provedor passa a ser independente: as mensagens ausentes em espanhol usam o texto de origem como alternativa, em vez de recorrer ao texto em francês. A comparação usa a string literal do idioma, então mantenha a grafia do idioma consistente em toda a aplicação.

Troque o idioma e o catálogo juntos #

Armazene a entrada de renderização em um par, como { locale: "fr", messages: frenchMessages }. Carregue o próximo mapa e substitua o par em uma única atualização de estado. Alterar apenas o idioma pode deixar o texto em francês com a formatação de números em espanhol.

Enquanto o próximo catálogo é carregado, mantenha o par anterior visível ou exiba um estado de carregamento, conforme o design de interação da aplicação. Em aplicações com roteamento, siga a receita correspondente de Next Pages ou TanStack; os seletores de idioma de cada uma carregam a nova entrada de maneiras diferentes.

Crie um objeto Lingo sem usar um hook #

Use createLingo(locale: string, messages?: Messages): Lingo quando uma função precisar de uma string fora de um componente React:

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

const l = createLingo("en-US");
const title = l.text("Account settings", { context: "Settings page title" });
const percentage = l.percent(0.125, { maximumFractionDigits: 1 });

Isso retorna Account settings e formata a proporção como 12.5% nesse idioma. Não faz nenhuma solicitação de tradução nem se inscreve em um provedor. Crie um novo objeto quando o idioma ou as mensagens mudarem.

Tanto createLingo quanto useLingo expõem locale, direction, script e region. Use os metadados do idioma para aplicar atributos ao documento e mantenha as mesmas entradas durante a hidratação.