Solucionar problemas com mensagens no React
Descubra em que ponto uma mensagem perde a tradução, os valores, as tags ou o idioma entre a extração e a renderização.
Acompanhe a mensagem que de fato aparece na tela. O texto de origem e o contexto determinam a chave; o provedor mais próximo fornece o catálogo; o modelo selecionado é formatado com os valores da chamada. Verificar essas entradas geralmente ajuda a localizar a falha sem alterar manualmente as chaves geradas.
useLingo lança uma exceção fora de um provedor #
Coloque LingoProvider acima do componente que chama o hook, inclusive em testes e prévias isoladas. Um provedor retornado pelo mesmo componente fica abaixo desse hook. Mova o hook para um componente filho ou use createLingo(locale, messages) em uma função que não renderize por meio do contexto do React.
Use o React 19 com a implementação atual do provedor. A sintaxe abreviada de contexto do React 19 usada nessa implementação não se torna compatível com o React 18 só porque o pacote aceita uma faixa mais ampla de versões nas dependências de pares.
O texto de origem aparece no lugar da tradução #
- Verifique os valores reais de
localeemessagesdo provedor mais próximo. As mensagens devem ser um mapa de hashes para strings, não uma URL de arquivo, uma promessa ouLocaleFile. - Calcule
computeKey(source, context)a partir da chamada exata. Procure essa chave no mapa fornecido. Alterações na pontuação, nos espaços em branco e no contexto podem gerar uma nova identidade. - Se a extração não incluir a chave, use texto de origem e contexto literais com um receptor compatível, como
l.text(...), e execute a extração novamente. Uma chamada calculada pode ser renderizada em tempo de execução sem que seja possível extraí-la. - Se a chave estiver no catálogo de origem, mas não no de destino, obtenha a tradução concluída e recarregue o mapa. O envio, por si só, não coloca o arquivo na aplicação.
- Se a chave estiver no arquivo, mas não no provedor, verifique os caminhos do carregador e a seleção de rotas. Carregamento de catálogos mostra a associação por chave de origem necessária quando o JSONC traduzido perde os metadados.
Tanto valores ausentes quanto strings vazias fazem com que o texto de origem seja usado como alternativa. Os avisos de desenvolvimento distinguem os dois casos e são deduplicados por chave e idioma. Em produção, esses diagnósticos são suprimidos; por isso, um console vazio não garante que o catálogo esteja completo.
O carregador do Next retorna {} quando um arquivo está ausente, mas pode lançar uma exceção se o JSONC estiver malformado. O catálogo integrado do TanStack captura falhas de arquivo ausente, carregamento e análise como {} e armazena esse resultado em cache. Nos dois casos, recorrer ao texto de origem pode manter a página legível e, ao mesmo tempo, ocultar um problema de carregamento.
Um marcador de posição ou uma expressão ICU continua visível #
Verifique o objeto values que chega à chamada. Quando faltam valores simples, {name} permanece visível. Sem um objeto de valores, o ambiente de execução retorna o modelo selecionado sem aplicar formatação.
Para uma mensagem ICU complexa, verifique a sintaxe, os nomes dos argumentos e os tipos de valores da tradução de destino selecionada. Um erro de análise ou formatação retorna esse mesmo modelo e emite um erro de desenvolvimento deduplicado. Assim, uma tradução malformada pode aparecer no lugar do texto de origem em inglês. Corrija o modelo ou forneça o argumento ausente e renderize o caso novamente.
As declarações geradas verificam os argumentos detectados no texto de origem, mas não validam a sintaxe de destino nem identificam todos os marcadores de posição aninhados em uma ramificação ICU. Teste a ramificação afetada com valores reais.
Um link desaparece ou as tags aparecem como texto #
Mensagens com formatação usam funções de retorno de chamada nomeadas, como tags.link. Use exatamente o nome da tag traduzida e mantenha o destino na função de retorno de chamada. Tags pareadas desconhecidas, tags de fechamento automático e tags de abertura sem fechamento permanecem como texto literal.
Use nomes distintos para elementos aninhados. O analisador não aceita aninhamento repetido com o mesmo nome. Mensagens com formatação aceitam marcadores de posição simples, não a gramática ICU completa; para isso, use as funções auxiliares de gramática de texto. Texto com formatação mostra os formatos aceitos.
A URL muda, mas o idioma não #
Substitua o idioma e o catálogo juntos. Atualizar apenas o idioma pode fazer com que um texto em francês seja formatado com as regras do espanhol. Verifique também os provedores aninhados: um provedor filho com outro idioma é independente e não herda o catálogo do provedor pai.
Siga o mecanismo de troca de idioma do adaptador selecionado. O Next Pages usa a navegação do roteador e um cookie de idioma. O TanStack usa links comuns para que uma nova requisição possa carregar o novo catálogo.
O texto, a direção ou as datas mudam durante a hidratação #
Compare as entradas do servidor e do cliente: revisão do catálogo, idioma, valores, marca de tempo, fuso horário e referência de tempo relativo. Defina lang e dir do documento na estrutura base do framework; o provedor base não altera esses atributos. Em seguida, teste o HTML inicial e a página hidratada usando a lista de verificação de renderização no servidor.