Localizar mensagens interativas com formatação
Traduza uma frase completa sem que o código React perca o controlo das ligações, dos componentes e dos valores.
«Leia a política antes de continuar» é uma única frase, mesmo quando «política» é uma ligação. Mantê-la numa só tradução permite colocar a ligação no lugar certo noutro idioma, sem retirar ao código da aplicação o controlo do destino.
O método rich do pacote React representa essa ligação como um espaço reservado com nome. O catálogo fornece a frase; um renderizador React fornece o componente para esse espaço.
Renderizar uma frase completa com uma ligação #
Instale @lingo.dev/react numa aplicação React 19 existente. Este exemplo local usa um catálogo de exemplo em espanhol e não requer qualquer pedido de tradução:
npm install @lingo.dev/reactimport { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";
const messages = {
[computeKey(
"Read the <policy>policy</policy> before continuing.",
"Notice before account creation",
)]: "Antes de continuar, lee la <policy>política</policy>.",
};
function ConsentNotice() {
const l = useLingo();
return (
<p>
{l.rich("Read the <policy>policy</policy> before continuing.", {
context: "Notice before account creation",
tags: {
policy: (children) => <a href="/policy">{children}</a>,
},
})}
</p>
);
}
export function App() {
return (
<LingoProvider locale="es" messages={messages}>
<ConsentNotice />
</LingoProvider>
);
}O parágrafo deverá apresentar «Antes de continuar, lee la política.» A frase traduzida muda a posição da referência à política, mas a ligação continua a apontar para /policy. O texto de origem literal e o contexto na chamada também permitem reconhecer a mensagem durante a extração. computeKey constrói a identidade real dos dados de teste, em vez de depender de um hash inventado.
Atualmente, o fornecedor usa a sintaxe de contexto do React 19, embora o pacote declare compatibilidade com React 18/19 nas dependências entre pares. Verifique o funcionamento com React 18 separadamente. O guia de início rápido do React explica como configurar o fornecedor e o primeiro catálogo.
Manter os valores e o comportamento no código #
O nome policy identifica um espaço reservado, não um elemento HTML fornecido por quem traduz. O respetivo renderizador controla o destino e o comportamento. Determine o destino específico de cada idioma a partir de um mapeamento de rotas conhecido no código; mantenha os processadores de eventos e os atributos HTML arbitrários fora do catálogo.
Para valores variáveis, use marcadores de posição com nome:
const greeting = l.text("Welcome, {name}", {
context: "Greeting on the signed-in account page",
values: { name },
});
const countLabel = l.plural(
count,
{ one: "# item", other: "# items" },
{ context: "Number of items in the cart" },
);
const roleLabel = l.select(
role,
{ admin: "Administrator", other: "Member" },
{ context: "Account role label" },
);Estas chamadas devem estar dentro de um componente com const l = useLingo() e valores da aplicação para name, count e role. text devolve texto simples, plural determina a forma gramatical em função da contagem e select faz a correspondência exata com um seletor, usando other como alternativa. O processamento de texto formatado suporta etiquetas com nome e interpolação simples de valores; não executa o formatador ICU complexo usado no processamento de texto simples. Use plurais, datas e números para essas decisões em tempo de execução.
Mantenha o texto de origem estático. Inserir o nome de uma pessoa na cadeia de origem criaria um texto diferente para cada pessoa e impediria uma extração fiável. O contexto deve explicar a utilização, por exemplo, «Rótulo da função da conta», porque o texto de origem e o contexto determinam, em conjunto, a identidade. Quando já existirem traduções, altere o contexto de forma deliberada.
Substituir os dados de teste locais por catálogos extraídos #
Com a versão atual da CLI instalada, execute:
lingo extract --src src --source-locale enSe não indicar caminhos alternativos, este comando escreve locales/en.jsonc e lingo.d.ts. Examine o texto de origem, o contexto e a chave extraídos. Inclua a declaração na configuração TypeScript da aplicação. A extração suporta chamadas de mensagens reconhecíveis; não deteta cadeias de origem arbitrárias geradas dinamicamente.
Siga o guia de início rápido da CLI para se autenticar e associar um motor de localização. Em seguida, selecione este ficheiro de origem locales/en.jsonc e os idiomas de destino necessários em .lingo/config.json. Traduza e obtenha o catálogo através desse workflow de ficheiros. Use o procedimento de carregamento de catálogos para analisar JSONC, selecionar as chaves ativas da revisão de origem correspondente e fornecer as cadeias de destino ao fornecedor. O tradutor geral de ficheiros não preserva os comentários do catálogo de origem no resultado de destino.
Carregue o mesmo aviso com o catálogo em espanhol obtido. Quando faltam entradas ou estas estão vazias, é usado o texto de origem como alternativa. Por isso, compare também as chaves de destino necessárias, não apenas o resultado visível.
Testar a interação e os casos malformados #
Abra a ligação da política com o teclado e verifique o respetivo nome acessível. Leia a pontuação em redor depois de a ligação mudar de posição. Uma tradução completa deve preservar tanto o significado da frase como a ação disponível para quem a lê.
Num catálogo local de teste, remova o processador de etiquetas, introduza uma etiqueta desconhecida e deixe uma etiqueta por fechar. O renderizador atual mantém como texto a marcação desconhecida ou sem par; o emparelhamento de etiquetas aninhadas com o mesmo nome tem limitações. Não é um renderizador de HTML arbitrário nem um validador que rejeite todas as mensagens malformadas.
Para texto simples, verifique os valores em falta e as mensagens ICU complexas malformadas: os marcadores de posição não resolvidos ou o modelo sem formatação podem continuar visíveis, com diagnósticos em ambiente de desenvolvimento. Para mensagens de contagem e de função, teste as categorias de plural do idioma de destino e uma função desconhecida. Consulte a referência de texto formatado e as orientações de teste do React para conhecer o comportamento exato subjacente a estas verificações.