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:
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 precisa | Use |
|---|---|
| Texto simples com valores | l.text. |
| Links, ênfase ou outro elemento React | l.rich, com funções de retorno nomeadas para renderização. |
| Gramática que varia conforme a quantidade ou uma escolha por categoria | l.plural e l.select. |
| Números, datas, listas ou operações de texto que levam o idioma em conta | Mé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.