Solução de problemas da integração com Astro

A maioria dos problemas com a integração do Astro aparece como uma página que permanece no seu idioma de origem ou um URL de idioma que retorna 404. O log do servidor nomeia a causa da maioria deles, e cada aviso é registrado uma vez.

Verifique os básicos primeiro

1. O servidor de build ou de desenvolvimento é iniciado. Se falhar com "set UNIVERSALLY_API_KEY in .env or pass apiKey in the integration options", a chave está faltando. Coloque-a em .env ao lado de astro.config.mjs, ou no ambiente em que o build é executado. Em Node anterior a 20.12, os arquivos .env são ignorados, então use o ambiente.
2. A chave é a de 64 caracteres da página Configuração ou Configurações de API do projeto. Uma chave pk_ falha na chamada de idiomas e no build.
3. O switch Ativo do idioma está ativado em Todos os Idiomas.
4. O texto passa por t(). Nada fora de t() é traduzido.

A primeira renderização mostra o texto de origem

Causa. A string ainda não tinha tradução. Ela é reportada para Universally após a resposta e traduzida em segundo plano. Correção. Recarregue após um ou dois segundos. Uma string perdida é reportada novamente em sua próxima renderização, então ela chega em uma solicitação posterior. Veja Atualizações de tradução no Astro.

Um idioma retorna 404 após você adicioná-lo

Causa. Os idiomas são lidos uma vez, quando sua configuração do Astro é executada. Um idioma adicionado ou alterado depois não é uma rota no build em execução. Correção. Reinicie o servidor de desenvolvimento, ou reconstrua e reimplant.

Se o idioma estava lá, mas seu catálogo falhou ao carregar, o log mostra universally: could not preload ..., e esse idioma não é tentado novamente até a reinicialização. Corrija a causa e reinicie.

Uma string permanece sem tradução enquanto o resto é traduzido

Causa. O texto de origem é a chave, e ele não corresponde à string de origem no painel. Um espaço extra, uma palavra alterada ou pontuação diferente a tornam uma string diferente. Um URL dentro da string a torna uma chave diferente em cada página. Correção. Compare o argumento de t() com a string de origem na tela Traduções, caractere por caractere. Mantenha <a> fora de t(). Veja Traduzir páginas no Astro.

Nenhum link hreflang no HTML

Causa. site não está definido em astro.config.mjs, então nenhuma URL absoluta pode ser criada. O log diz "site is not set in your Astro config, so no hreflang links were rendered." Correção. Defina site para o seu domínio, como site: 'https://example.com'. Verifique também se <UniversallyHead /> está dentro de <head> no seu layout. t(), href() e o seletor funcionam de qualquer maneira. Veja tags hreflang.

No modo proxy, um único idioma ausente significa que ele ainda não tem um hostname ativo. Veja Astro com subdomínios de idioma.

Uma edição no painel não está sendo exibida

Causa. O push para /_universally/revalidate não chegou ao seu servidor e a verificação ainda não ocorreu. Com revalidateSeconds em 0 e um endpoint inacessível, a edição nunca chega. Correção. Aguarde até revalidateSeconds (60 por padrão). Para edições instantâneas, torne https://{seu domínio}/_universally/revalidate acessível pela internet. Com várias instâncias de servidor, as outras se atualizam por polling. Veja Implantar um site Astro com Universally.

Um site estático não exibe novas strings ou edições

Causa. Uma compilação estática é HTML em disco. Ela não tem polling nem endpoint de push. Correção. Recompile. Quando o log de compilação disser N new strings translated. Rebuild to include them., compile mais uma vez e, em seguida, implante.

Cada página permanece no idioma de origem

Causa. O projeto usou suas palavras pré-pagas, então Universally retorna apenas strings que já possui. O log diz universally: word limit reached, {variant} keeps serving source text. Correção. Adicione palavras ao projeto. As strings que já foram traduzidas continuam sendo exibidas enquanto isso, e as ausentes são reportadas novamente em sua próxima renderização. Veja Limites de uso e Acompanhe seu uso.

O endpoint de push retorna 401

Causa. A assinatura não corresponde à metade privada da chave em seu servidor, ou o ts do corpo está mais de 5 minutos atrasado em relação ao relógio do seu servidor. Uma chave regenerada causa isso até você reimplantar. Correção. Defina a chave atual em seu host e reimplantar, e verifique o relógio do servidor. O formato completo está em Opções de integração do Astro.

O script do seletor está faltando

Causa. switcher: false está definido, ou a chave não tem metade pública (uma chave sk_). O segundo caso registra um aviso. Correção. Remova switcher: false, ou substitua a chave pela de 64 caracteres.

Ainda travado

Entre em contato com o suporte com o domínio do seu projeto, sua versão do Astro, sua configuração output e todas as linhas universally: do log do servidor.