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:

sh
npm install @lingo.dev/react
tsx
import { 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:

tsx
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:

sh
lingo extract --src src --source-locale en

Sem 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.