Mensagens em React

Mantenha o texto de origem e o contexto nos componentes e renderize catálogos traduzidos com valores, gramática e elementos React.

A mensagem de um componente deve ficar junto da ação que explica. “Salvar” em um formulário envia as alterações; “Salvar” em um artigo cria um favorito. Manter o texto de origem junto de seu significado ajuda os tradutores a fazer essa distinção e permite que os desenvolvedores entendam o componente sem procurar uma chave em outro arquivo.

@lingo.dev/react usa chamadas explícitas de mensagem:

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

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

O texto de origem e o contexto identificam uma mensagem em um catálogo, que mapeia chaves para strings traduzidas. Um provedor fornece esse catálogo e o idioma ativo. O componente recebe o texto traduzido ou, quando a entrada não existe ou está vazia, o texto de origem.

De um componente a outro idioma #

Primeiro, renderize uma tradução local. Um catálogo pequeno permite visualizar a busca sem precisar de uma conta ou fazer uma requisição de rede.

No workflow da aplicação, lingo extract reúne as chamadas reconhecíveis em um catálogo de origem JSONC e gera declarações TypeScript. A CLI envia esse arquivo para tradução e recupera a versão traduzida. Seu carregador converte o arquivo no mapa de strings do provedor. A seção Extração e carregamento de catálogos apresenta o processo completo, incluindo como preservar as mensagens ativas quando o JSONC traduzido perde os comentários de metadados.

A renderização é local. O ambiente de execução não se conecta a um engine de localização nem contém uma chave de API. Mantenha a tradução no servidor na integração com a API e entregue os catálogos resultantes à aplicação pelo processo normal de compilação ou de carregamento por requisição.

Escreva a mensagem de que o leitor precisa #

Use uma frase completa com marcadores de posição em vez de concatenar fragmentos traduzidos separadamente. Em outro idioma, o nome, a quantidade ou o link podem aparecer em outro ponto da frase.

O que a mensagem precisaUse
Texto simples com valoresl.text.
Links, ênfase ou outro elemento Reactl.rich, com funções de retorno nomeadas para renderização.
Gramática que varia conforme a quantidade ou uma escolha por categorial.plural e l.select.
Números, datas, listas ou operações de texto que levam o idioma em contaMétodos de formatação, que usam Intl nativo.

A referência de provedor e hooks explica os catálogos aninhados e o uso de createLingo em código fora dos componentes. A seção Metadados de idioma fornece informações sobre direção, sistema de escrita e região para orientar as decisões sobre o documento e o layout.

Conecte a aplicação a partir das mensagens #

Os adaptadores Next.js Pages e TanStack Start conectam os catálogos aos respectivos sistemas de roteamento. Em outras configurações, carregue o idioma e as mensagens antes da renderização e preserve esse par durante a renderização no servidor e a hidratação.

Use tipos gerados para detectar erros no texto de origem, no contexto e nos valores durante a edição. Use testes de renderização para verificar os modelos realmente carregados. Se uma tradução não aparecer, a seção de solução de problemas acompanha a busca do componente até o catálogo.

Exportações #

A raiz exporta LingoProvider, useLingo, createLingo e computeKey, além dos tipos LingoProviderProps, Lingo, Messages, LingoMessages, MessageKey, TextOptions, RichOptions, PluralForms, SelectForms e FormatMethods. O ponto de entrada separado @lingo.dev/react/testing exporta withLingo e renderStatic.