Migre mensagens existentes do React

Migre um pequeno conjunto de mensagens de teste do React para mensagens explícitas com texto de origem e contexto, sem perder placeholders, comportamento de pluralização ou traduções aceitas.

Um catálogo React existente já reúne decisões importantes: identificadores de busca, regras de interpolação, comportamento de pluralização e traduções que alguém já revisou. A migração para mensagens com texto de origem e contexto deve preservar esse trabalho. Comece convertendo um componente completo, mapeie suas traduções aceitas para os novos identificadores e compare o resultado renderizado antes de ampliar a migração.

Registre o comportamento atual antes de alterar a identidade #

Escolha um componente com um rótulo, uma variável, um link, uma contagem e uma mensagem condicional. Registre as chaves antigas, os textos de origem e de destino, a sintaxe de interpolação, o namespace e o idioma do provedor. Renderize o componente no idioma de origem e em um idioma de destino, usando valores fixos. Assim, você terá um resultado concreto a preservar durante a migração.

Por exemplo, uma chamada existente no estilo do i18next poderia ser:

tsx
t("account.greeting", { name });

O catálogo de origem poderia conter Welcome, {{name}}. Não copie essa sintaxe de interpolação sem ajustes para um novo contrato de mensagens. A mensagem explícita do React usa uma variável nomeada {name}:

tsx
l.text("Welcome, {name}", {
  context: "Greeting on the signed-in account page",
  values: { name },
});

A mudança de delimitadores mostrada aqui é específica dessa configuração da biblioteca de origem. Verifique a biblioteca instalada antes de converter outras mensagens: delimitadores de interpolação personalizados e convenções de pluralização podem exigir ajustes diferentes.

Mapeie o comportamento das mensagens, não apenas os nomes dos métodos #

Use text para mensagens simples com valores, rich para espaços reservados nomeados para componentes, plural para formas que dependem da contagem e select para alternativas de valor exato com other como opção padrão. Mensagens interativas com formatação rica traz um exemplo completo dos quatro casos.

Um componente antigo de mensagens com formatação rica pode representar links por índices. Substitua esses índices por espaços reservados com nomes significativos e mantenha o destino do link no código. Preserve os nomes, os tipos e as funções semânticas das variáveis. Um catálogo antigo de plurais pode armazenar chaves com sufixos; o novo ambiente de execução monta a mensagem plural a partir das formas. Verifique o comportamento no idioma de destino em vez de apenas renomear as chaves com sufixos mecanicamente.

Escolha um contexto que explique como a mensagem é usada. A nova identidade é definida pelo texto de origem e pelo contexto, não por account.greeting. Mantenha uma tabela de migração com a chave antiga, o idioma, a nova chave extraída e as conversões de sintaxe necessárias. No caso da saudação, essa linha registra a conversão de {{name}} para {name}. Com esse mapeamento, um revisor pode rastrear o texto aceito até o novo catálogo e identificar as mensagens que ainda não foram mapeadas.

Extraia e importe um pequeno catálogo com cuidado #

Instale @lingo.dev/react e configure LingoProvider seguindo o guia de início rápido do React. Use o React 19 para a implementação atual do provedor; a faixa de compatibilidade com o React 18 declarada como dependência de pares não dispensa testes em uma aplicação mais antiga. Depois de converter o componente, execute a CLI instalada:

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

Se os caminhos padrão não tiverem sido alterados, inspecione locales/en.jsonc e lingo.d.ts. Localize cada mensagem de origem e seu contexto e copie a chave realmente extraída para a tabela de migração. Manter a chave antiga ou inventar um hash romperia a associação entre a tradução de destino e a busca em tempo de execução.

Insira cada tradução de destino aceita na nova chave correspondente do mapeamento. Converta com cuidado a sintaxe de placeholders, espaços reservados de formatação rica e plurais, preservando o significado. Carregue um mapa de destino que associe hashes a strings pelo workflow de carregamento de catálogos, usando as chaves ativas da origem correspondente quando não houver metadados de destino. Mantenha as entradas não mapeadas visíveis como trabalho pendente, em vez de classificá-las como obsoletas.

Forneça a LingoProvider o idioma solicitado junto com as respectivas mensagens de destino. Durante a migração incremental, mantenha os provedores antigo e novo envolvendo seus respectivos pontos de chamada. O contrato do provedor explica a mesclagem para o mesmo idioma e o isolamento entre idiomas diferentes; verifique esses comportamentos ao migrar uma tela aninhada.

Verifique os casos de mensagens ausentes e malformadas #

Renderize o conjunto de teste com os mesmos valores usados antes da migração. Compare o significado exibido, a posição das variáveis, o comportamento dos links, o resultado dos plurais e a seleção da opção padrão. Inclua contagens de zero, um e valores maiores; valores longos para as variáveis; e um valor de seleção desconhecido.

Remova uma entrada de destino em um conjunto de teste local e verifique se o texto de origem é exibido como alternativa. Mensagens ausentes ou vazias podem exibir o texto de origem, então uma tela utilizável não comprova a cobertura das traduções de destino. Execute as verificações de consistência da extração e do TypeScript, incluindo as declarações geradas. Em seguida, execute os testes de renderização existentes da aplicação. Os tipos comprovam a compatibilidade das chamadas, não a qualidade da tradução.

Se houver uma tag de formatação rica ou uma mensagem ICU malformada, inspecione a saída e os diagnósticos. O novo ambiente de execução pode deixar a marcação literal ou um modelo de mensagem sem formatação visível. Por isso, compare esse comportamento com os requisitos da aplicação antes de remover o ambiente de execução antigo. O guia de solução de problemas do React documenta essas limitações.

Trate a assistência de agentes como trabalho sujeito a revisão #

Peça ao agente para inspecionar a biblioteca existente, preservar um mapeamento de chaves, identificar padrões não compatíveis e separar as alterações no código-fonte da importação do catálogo. Revise as alterações propostas no código-fonte e no catálogo antes de aplicá-las.

Amplie a migração por componente ou namespace depois que o conjunto de teste passar nas verificações de renderização e nas verificações nativas. Mantenha os dois catálogos até que cada ponto de chamada e cada tradução de destino aceita tenham um destino verificado. Remova o provedor e a dependência antigos somente quando nenhum código restante os utilizar. Os clientes de API e os adaptadores de roteador têm responsabilidades distintas; trocar o ambiente de execução de mensagens não os substitui.