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 acompanhar a ação que explica. «Guardar» num formulário submete alterações; «Guardar» num artigo cria um marcador. Manter o texto de origem junto do seu significado permite aos tradutores perceber essa distinção e aos programadores compreender o componente sem terem de procurar uma chave noutro ficheiro.
O @lingo.dev/react utiliza chamadas explícitas de mensagens:
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 num catálogo, que associa chaves a cadeias de texto traduzidas. Um fornecedor disponibiliza esse catálogo e o idioma ativo. O componente recebe o texto traduzido ou, se a entrada não existir ou estiver vazia, o texto de origem.
De um componente para outro idioma #
Comece por renderizar uma tradução local. Um pequeno catálogo permite perceber como funciona a pesquisa, sem precisar de uma conta nem de fazer um pedido de rede.
No workflow da aplicação, o lingo extract reúne as chamadas reconhecíveis num catálogo de origem em JSONC e gera declarações TypeScript. A CLI envia esse ficheiro para tradução e obtém a versão traduzida. O carregador converte o ficheiro no mapa de cadeias de texto do fornecedor. A secção Extração e carregamento de catálogos descreve 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 contacta um motor de localização nem contém uma chave de API. Mantenha a tradução no servidor na integração com a API; disponibilize os catálogos resultantes à aplicação através do processo habitual de compilação ou de carregamento por pedido.
Escreva a mensagem de que o leitor precisa #
Utilize uma frase completa com marcadores de posição, em vez de concatenar fragmentos traduzidos separadamente. Noutro idioma, o nome, a contagem ou a ligação podem ocupar outra posição na frase.
| O que a mensagem precisa | Utilize |
|---|---|
| Texto simples com valores | l.text. |
| Ligações, ênfase ou outro elemento React | l.rich, com funções de retorno nomeadas para a renderização. |
| Gramática que depende da quantidade ou uma escolha por categoria | l.plural e l.select. |
| Números, datas, listas ou operações de texto adaptadas ao idioma | Métodos de formatação, que utilizam o Intl nativo. |
A referência sobre fornecedor e hooks explica os catálogos aninhados e o createLingo para código fora dos componentes. Os metadados do idioma fornecem informações sobre a direção do texto, o sistema de escrita e a região para orientar as escolhas relativas ao documento e à disposição dos elementos.
Integre a aplicação em torno das mensagens #
Os adaptadores Next.js Pages e TanStack Start ligam os catálogos aos respetivos sistemas de encaminhamento. Noutras configurações, carregue o idioma e as mensagens antes da renderização e mantenha esse par durante a renderização no servidor e a hidratação.
Utilize os tipos gerados para detetar erros no texto de origem, no contexto e nos valores durante a edição. Recorra a testes de renderização para verificar os modelos efetivamente carregados. Se uma tradução não aparecer, a secção de resolução de problemas acompanha a pesquisa desde o componente até ao 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.