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:

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

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" },
);

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:

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

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