Migrar mensagens React existentes

Migre um pequeno conjunto de mensagens de teste em React para mensagens com texto de origem e contexto explícitos, sem perder marcadores de posição, comportamento de pluralização ou traduções aceites.

Um catálogo React existente já reflete decisões importantes: identificadores de pesquisa, regras de interpolação, comportamento de pluralização e traduções que alguém já reviu. A migração para mensagens com texto de origem e contexto deve preservar esse trabalho. Converta primeiro um componente completo, associe as traduções aceites aos novos identificadores e compare o resultado apresentado antes de alargar a migração.

Registe o comportamento atual antes de alterar os identificadores #

Escolha um componente com uma etiqueta, uma variável, uma ligação, uma contagem e uma mensagem condicional. Guarde as chaves antigas, os textos de origem e de destino, a sintaxe de interpolação, o espaço de nomes e o idioma do fornecedor. Apresente o componente no idioma de origem e num idioma de destino, com valores fixos. Assim, terá um resultado concreto a preservar durante a migração.

Por exemplo, uma chamada existente ao estilo do i18next pode ser:

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

O respetivo catálogo de origem pode conter Welcome, {{name}}. Não copie essa sintaxe de interpolação sem alterações para um novo contrato de mensagens. A mensagem React explícita utiliza uma variável com nome, {name}:

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

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

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

Utilize text para mensagens simples com valores, rich para pontos de inserção de componentes identificados por nome, plural para formas que dependem da contagem e select para alternativas baseadas em valores exatos, com other como opção de recurso. Em Mensagens interativas com formatação, encontra um exemplo completo dos quatro casos.

Um componente antigo de mensagens com formatação pode codificar ligações por índice. Substitua esses índices por pontos de inserção com nomes descritivos e mantenha o destino da ligação no código. Preserve os nomes, os tipos e as funções semânticas das variáveis. Um catálogo antigo de plurais pode guardar chaves com sufixos; o novo ambiente de execução constrói a mensagem no plural a partir de formas. Verifique o comportamento do idioma de destino, em vez de se limitar a mudar mecanicamente os nomes das chaves com sufixos.

Escolha um contexto que explique como a mensagem é utilizada. O novo identificador deriva do texto de origem e do contexto, e não de account.greeting. Mantenha uma tabela de migração com a chave antiga, o idioma, a nova chave extraída e eventuais conversões de sintaxe. No caso da saudação, essa linha regista a conversão de {{name}} para {name}. Este mapeamento permite a quem faz a revisão acompanhar a passagem dos textos aceites para o novo catálogo e identificar as mensagens que continuam sem correspondência.

Extraia e importe um pequeno catálogo de forma criteriosa #

Instale @lingo.dev/react e configure LingoProvider seguindo o guia de início rápido de React. Utilize React 19 para a implementação atual do fornecedor; o intervalo de versões de React 18 declarado como dependência de pares não dispensa os testes numa aplicação mais antiga. Depois de converter o componente, execute a CLI instalada:

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

Se não tiver alterado os caminhos predefinidos, inspecione locales/en.jsonc e lingo.d.ts. Localize cada mensagem de origem e o respetivo contexto e copie a chave efetivamente extraída para a tabela de migração. Manter a chave antiga ou inventar um hash quebraria a correspondência entre a tradução de destino e a pesquisa em tempo de execução.

Coloque cada tradução aceite sob a nova chave que lhe corresponde. Converta criteriosamente a sintaxe dos marcadores de posição, dos pontos de inserção de conteúdo com formatação e dos plurais, preservando o significado. Carregue um mapa de hashes para textos de destino através do workflow de carregamento de catálogos, utilizando as chaves ativas da origem correspondente quando não existirem metadados de destino. Mantenha as entradas sem correspondência visíveis como trabalho por concluir, em vez de as classificar como obsoletas.

Forneça a LingoProvider o idioma pedido e as respetivas mensagens de destino em conjunto. Durante a migração incremental, mantenha os fornecedores antigo e novo a envolver o código que utiliza cada um deles. O contrato do fornecedor explica a combinação de mensagens do mesmo idioma e o isolamento entre idiomas diferentes; verifique estes aspetos ao migrar um ecrã aninhado.

Verifique os casos de mensagens em falta ou malformadas #

Apresente o conjunto de teste com os mesmos valores utilizados antes da migração. Compare o significado visível, a posição das variáveis, o comportamento das ligações, o resultado da pluralização e a seleção da opção de recurso. Inclua contagens de zero, um e valores superiores; valores longos nas variáveis; e um valor de seleção desconhecido.

Remova uma entrada de destino num conjunto de teste local e confirme que o texto de origem é apresentado como recurso. As mensagens em falta ou vazias podem apresentar o texto de origem, pelo que um ecrã utilizável não comprova a cobertura das traduções de destino. Execute as verificações de consistência da extração e as verificações de TypeScript, incluindo as declarações geradas. Em seguida, execute os testes de apresentação existentes na aplicação. Os tipos asseguram a compatibilidade das chamadas, não a qualidade da tradução.

Se uma etiqueta de formatação ou uma mensagem ICU estiver malformada, inspecione o resultado e os diagnósticos. O novo ambiente de execução pode deixar visíveis a marcação literal ou um modelo sem formatação. Compare este comportamento com os requisitos da aplicação antes de remover o ambiente de execução antigo. O guia de resolução de problemas de React documenta essas limitações.

Reveja o trabalho realizado com a ajuda de um agente #

Peça ao agente que inspecione a biblioteca existente, preserve um mapeamento de chaves, identifique padrões não suportados e separe as alterações ao código-fonte da importação do catálogo. Reveja as alterações ao código-fonte e ao catálogo propostas pelo agente antes de as aplicar.

Alargue a migração por componente ou espaço de nomes depois de o conjunto de teste passar nas verificações de apresentação e nas verificações nativas. Mantenha ambos os catálogos até que todo o código que faz chamadas e todas as traduções aceites tenham um destino verificado. Remova o fornecedor antigo e a respetiva dependência apenas quando já não houver código que os utilize. Os clientes de API e os adaptadores de encaminhamento têm responsabilidades distintas; alterar o ambiente de execução das mensagens não os substitui.