Localize mensagens interativas com texto rico
Traduza uma frase completa sem tirar do código React o controle sobre links, componentes e valores.
“Leia a política antes de continuar” é uma única frase, mesmo quando “política” é um link. Traduzi-la como uma unidade permite reposicionar o link conforme o idioma, sem tirar do código da aplicação o controle sobre o destino.
O método rich do pacote React representa esse link como um espaço reservado nomeado. O catálogo fornece a frase; um renderizador React fornece o componente para esse espaço.
Renderize uma frase completa com link #
Instale @lingo.dev/react em uma aplicação React 19 existente. Este exemplo local usa um catálogo ilustrativo em espanhol e não exige nenhuma solicitação 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 deve exibir “Antes de continuar, lee la política.” A frase traduzida reposiciona a referência à política, enquanto o link continua apontando 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 provedor usa a sintaxe de contexto do React 19, embora o pacote declare React 18/19 como dependências de pares. Verifique o funcionamento com React 18 separadamente. O guia de início rápido do React explica como configurar o provedor e o primeiro catálogo.
Mantenha os valores e o comportamento no código #
O nome policy identifica um espaço reservado, não um elemento HTML fornecido por um tradutor. O renderizador desse espaço controla o destino e o comportamento. Resolva o destino específico de cada idioma com base em um mapeamento de rotas conhecido no código; mantenha os manipuladores de eventos e os atributos HTML arbitrários fora do catálogo.
Para valores variáveis, use marcadores de posição nomeados:
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" },
);Essas chamadas devem ficar dentro de um componente com const l = useLingo() e valores da aplicação para name, count e role. text retorna texto simples, plural resolve a gramática de acordo com a contagem e select busca uma correspondência exata para o seletor, com other como alternativa. O processamento de texto rico aceita tags nomeadas e interpolação simples de valores; ele não executa o formatador de 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 string de origem criaria um texto diferente para cada pessoa e impediria uma extração confiável. O contexto deve explicar o uso, como “Rótulo de função da conta”, pois o texto de origem e o contexto, juntos, determinam a identidade. Depois que as traduções existirem, altere o contexto de forma deliberada.
Substitua 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 enSem personalizar os caminhos, esse comando grava locales/en.jsonc e lingo.d.ts. Confira o texto de origem, o contexto e a chave extraídos. Inclua a declaração na configuração do TypeScript da aplicação. A extração aceita chamadas de mensagem reconhecíveis; ela não descobre strings de origem arbitrárias geradas dinamicamente.
Siga o guia de início rápido da CLI para se autenticar e vincular um engine de localização. Em seguida, selecione em .lingo/config.json esse arquivo de origem locales/en.jsonc real e os idiomas de destino necessários. Traduza e obtenha o catálogo por meio desse workflow de arquivos. Use o procedimento de carregamento de catálogos para analisar o JSONC, selecionar as chaves ativas da revisão de origem correspondente e fornecer as strings de destino ao provedor. O tradutor geral de arquivos não preserva os comentários do catálogo de origem na saída traduzida.
Carregue o mesmo aviso com o catálogo em espanhol obtido. Entradas ausentes ou vazias usam o texto de origem como alternativa, então compare também as chaves de destino necessárias, não apenas a saída visível.
Teste a interação e os casos de mensagens malformadas #
Acesse o link da política com o teclado e verifique seu nome acessível. Leia a pontuação ao redor depois que o link mudar de posição. Uma tradução completa deve preservar tanto o significado da frase quanto a ação disponível para o leitor.
Em um catálogo local de teste, remova o manipulador de tags, insira uma tag desconhecida e deixe uma tag sem fechamento. O renderizador atual mantém marcações desconhecidas ou sem par como texto; o pareamento de tags aninhadas com o mesmo nome tem limitações. Ele não é um renderizador de HTML arbitrário nem um validador que rejeita toda mensagem malformada.
Para texto simples, verifique os casos de valores ausentes e mensagens ICU complexas malformadas: marcadores de posição não resolvidos ou o modelo sem formatação podem continuar visíveis, com diagnósticos no ambiente de desenvolvimento. Para mensagens de contagem e função, teste as categorias de plural do idioma de destino e uma função desconhecida. Consulte a referência de texto rico e as orientações de teste do React para entender o comportamento exato em cada uma dessas verificações.