Fornecedor e hooks

Forneça um idioma e um catálogo, combine mensagens partilhadas com mensagens de página e mude de idioma sem misturar os dados de entrada da renderização.

LingoProvider disponibiliza um idioma e um catálogo a uma subárvore de componentes. useLingo() lê o fornecedor mais próximo e devolve os métodos de mensagens e de formatação correspondentes a esses dados de entrada.

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

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 fornecedor aceita Messages, um Record<string, string>, e não um caminho de ficheiro, uma promessa ou uma lista de entradas JSONC já analisada. O carregamento do catálogo gera este mapa.

Dados de entrada do fornecedor #

PropriedadeContrato
localeCadeia de caracteres obrigatória, utilizada nos diagnósticos de pesquisa de mensagens, na gramática e na formatação.
messagesMapa opcional de cadeias de caracteres com hashes como chaves; o valor predefinido é {}.
childrenSubárvore ReactNode obrigatória.

Mesmo com um catálogo vazio, a subárvore dispõe de formatação adaptada ao idioma; as chamadas de mensagens utilizam os respetivos modelos de origem. O fornecedor, por si só, não define o idioma nem a direção do documento.

Chame useLingo num componente abaixo do fornecedor. Se a chamada for feita fora de um fornecedor, é lançada uma exceção. Devolver um fornecedor a partir do mesmo componente não coloca o hook desse componente abaixo dele, pelo que deve separar o componente que contém o fornecedor do componente que lê o hook.

Combinar mensagens partilhadas com mensagens de página #

Os fornecedores aninhados com a mesma cadeia de caracteres de idioma combinam os seus mapas. As entradas do fornecedor filho substituem as entradas do fornecedor pai com as mesmas chaves, enquanto as restantes entradas do pai continuam disponíveis. Assim, uma rota pode acrescentar mensagens de página sem repetir as mensagens de navegação partilhadas.

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 fornecedor interno mudar para es, este torna-se independente: quando faltam mensagens em espanhol, recorre às mensagens de origem, em vez de utilizar o texto em francês. A comparação usa a cadeia de caracteres literal do idioma, pelo que deve escrever o idioma da mesma forma em toda a aplicação.

Mudar o idioma e o catálogo em conjunto #

Guarde os dados de entrada da renderização como um par, por exemplo, { locale: "fr", messages: frenchMessages }. Carregue o mapa seguinte e substitua o par numa única atualização de estado. Alterar apenas o idioma pode fazer com que o texto continue em francês, mas com formatação numérica espanhola.

Enquanto o catálogo seguinte é carregado, mantenha o par anterior visível ou apresente um estado de carregamento, de acordo com o design de interação da aplicação. Em aplicações com encaminhamento, siga a receita correspondente para Next Pages ou TanStack; os respetivos comutadores carregam os novos dados de entrada de formas diferentes.

Criar um objeto Lingo sem um hook #

Utilize createLingo(locale: string, messages?: Messages): Lingo quando uma função precisar de uma cadeia de caracteres 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 });

Esta chamada devolve Account settings e formata a proporção como 12.5% neste idioma. Não efetua qualquer pedido de tradução nem subscreve um fornecedor. Crie um novo objeto quando o idioma ou as mensagens mudarem.

Tanto createLingo como useLingo disponibilizam locale, direction, script e region. Utilize os metadados do idioma para aplicar atributos ao documento e mantenha os mesmos dados de entrada durante a hidratação.