Resolver problemas com mensagens em React

Descubra em que ponto entre a extração e a renderização uma mensagem perde a tradução, os valores, as etiquetas ou o idioma.

Siga a mensagem que aparece no ecrã. O texto de origem e o contexto determinam a chave; o fornecedor de contexto mais próximo fornece o catálogo; o modelo selecionado é formatado com os valores da chamada. Verificar estes dados permite, geralmente, localizar a falha sem alterar manualmente as chaves geradas.

useLingo lança uma exceção fora de um fornecedor de contexto #

Coloque LingoProvider acima do componente que chama o hook, incluindo em testes e pré-visualizações isoladas. Um fornecedor de contexto devolvido pelo próprio componente fica abaixo desse hook. Mova o hook para um componente filho ou utilize createLingo(locale, messages) numa função que não seja renderizada através do contexto do React.

Utilize o React 19 com a implementação atual do fornecedor de contexto. O facto de o pacote declarar um intervalo mais amplo de versões para as dependências pares não torna a sintaxe abreviada de contexto do React 19 compatível com o React 18.

Aparece o texto de origem em vez da tradução #

  1. Verifique os valores efetivos de locale e messages do fornecedor de contexto mais próximo. As mensagens têm de ser um mapa de hashes para cadeias de texto, não um URL de ficheiro, uma promessa ou LocaleFile.
  2. 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 ou no contexto podem criar uma nova identidade.
  3. Se a extração não incluir a chave, utilize um texto de origem e um contexto literais com um recetor suportado, como l.text(...), e execute novamente a extração. Uma chamada calculada pode ser renderizada em tempo de execução sem que seja possível extraí-la.
  4. Se o catálogo de origem tiver a chave, mas o de destino não, obtenha a tradução concluída e volte a carregar o mapa. O envio, por si só, não coloca o ficheiro na aplicação.
  5. Se o ficheiro tiver a chave, mas o fornecedor de contexto não, verifique os caminhos do carregador e a seleção de rotas. A secção Carregamento de catálogos mostra a junção pela chave de origem necessária quando o JSONC traduzido perdeu os metadados.

Tanto os valores em falta como as cadeias de texto vazias levam à utilização do texto de origem como alternativa. Os avisos em desenvolvimento distinguem os dois casos, e os duplicados são eliminados por chave e idioma. Em produção, estes diagnósticos são suprimidos, pelo que uma consola vazia não confirma que o catálogo esteja completo.

O carregador do Next devolve {} quando falta um ficheiro, mas pode lançar uma exceção se o JSONC estiver malformado. O catálogo integrado do TanStack trata as falhas por ausência de ficheiro, carregamento ou análise como {} e guarda esse resultado em cache. Em ambos os 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 devolve o modelo selecionado sem o formatar.

Numa mensagem ICU complexa, verifique a sintaxe, os nomes dos argumentos e os tipos dos valores da tradução de destino selecionada. Um erro de análise ou de formatação faz com que seja devolvido esse mesmo modelo e seja emitido um erro em desenvolvimento, sem duplicados. Por isso, pode aparecer uma tradução malformada em vez do texto de origem em inglês. Corrija o modelo ou forneça o argumento em falta e volte a renderizar esse caso.

As declarações geradas verificam os argumentos detetados no texto de origem, mas não validam a sintaxe de destino nem detetam todos os marcadores de posição aninhados num ramo ICU. Teste o ramo afetado com valores reais.

As mensagens com formatação utilizam funções de retorno com nome, como tags.link. Faça corresponder exatamente o nome da etiqueta traduzida e mantenha o destino da ligação na função de retorno. As etiquetas emparelhadas desconhecidas, as etiquetas de fecho automático e as etiquetas de abertura sem fecho permanecem como texto literal.

Utilize nomes distintos para os elementos aninhados. O aninhamento repetido de elementos com o mesmo nome não faz parte da estrutura suportada pelo analisador. As mensagens com formatação suportam marcadores de posição simples, não a gramática ICU completa; para esse efeito, utilize as funções auxiliares de gramática de texto. A secção Texto formatado mostra as formas suportadas.

O URL muda, mas o idioma não #

Substitua o idioma e o catálogo em conjunto. Atualizar apenas o idioma pode levar à formatação de texto francês com regras espanholas. Verifique também os fornecedores de contexto aninhados: um fornecedor filho com um idioma diferente é independente e não herda o catálogo do fornecedor pai.

Siga o mecanismo de mudança de idioma do adaptador selecionado. O Next Pages utiliza a navegação do encaminhador e um cookie de idioma. O TanStack utiliza ligações de âncora simples para que um novo pedido possa carregar o novo catálogo.

O texto, a direção ou as datas mudam durante a hidratação #

Compare os dados de entrada do servidor e do cliente: revisão do catálogo, idioma, valores, marca temporal, fuso horário e referência de tempo relativo. Defina lang e dir do documento na estrutura base da framework; o fornecedor de contexto base não os altera. Depois, teste o HTML inicial e a página hidratada com a lista de verificação da renderização no servidor.