Risoluzione dei problemi dell'integrazione Astro

La maggior parte dei problemi con l'integrazione Astro si manifesta come una pagina che rimane nella lingua di origine o un URL della lingua che restituisce 404. Il log del server indica la causa della maggior parte di essi e ogni avviso viene registrato una volta.

Controlla prima le basi

1. Il server di build o dev si avvia. Se fallisce con "set UNIVERSALLY_API_KEY in .env o passa apiKey nelle opzioni di integrazione", la chiave è mancante. Inseriscila in .env accanto a astro.config.mjs, o nell'ambiente in cui viene eseguita la build. Su Node versioni precedenti alla 20.12 i file .env vengono saltati, quindi usa l'ambiente.
2. La chiave è quella di 64 caratteri dalla pagina Setup o API Settings del progetto. Una chiave pk_ causa il fallimento della chiamata alle lingue e della build.
3. L'interruttore Live della lingua è attivo in Tutte le lingue.
4. Il testo passa attraverso t(). Nulla al di fuori di t() viene tradotto.

Il primo rendering mostra il testo sorgente

Causa. La stringa non aveva ancora una traduzione. Viene segnalata a Universally dopo la risposta e tradotta in background. Correzione. Ricarica dopo uno o due secondi. Una stringa mancante viene segnalata di nuovo al suo prossimo rendering, quindi arriva in una richiesta successiva. Vedi Aggiornamenti delle traduzioni in Astro.

Una lingua restituisce 404 dopo averla aggiunta

Causa. Le lingue vengono lette una volta, quando viene eseguita la configurazione di Astro. Una lingua aggiunta o attivata successivamente non è un percorso nella build in esecuzione. Correzione. Riavvia il server di sviluppo, o ricostruisci e ridistribuisci.

Se la lingua era presente ma il suo catalogo non è riuscito a caricarsi, il log mostra universally: could not preload ..., e quella lingua non viene ritentata fino al riavvio. Correggi la causa e riavvia.

Una stringa rimane non tradotta mentre le altre si traducono

Causa. Il testo sorgente è la chiave, e non corrisponde alla stringa sorgente nel dashboard. Uno spazio extra, una parola cambiata, o una punteggiatura diversa la rendono una stringa diversa. Un URL all'interno della stringa la rende una chiave diversa su ogni pagina. Correzione. Confronta l'argomento di t() con la stringa sorgente nella schermata Traduzioni, carattere per carattere. Tieni <a> al di fuori di t(). Vedi Traduci pagine in Astro.

Nessun link hreflang nell'HTML

Causa. site non è impostato in astro.config.mjs, quindi non è possibile creare un URL assoluto. Il log dice "site is not set in your Astro config, so no hreflang links were rendered." Correzione. Imposta site sul tuo dominio, ad esempio site: 'https://example.com'. Verifica anche che <UniversallyHead /> sia all'interno di <head> nel tuo layout. t(), href() e lo switcher funzionano in entrambi i casi. Vedi tag hreflang.

In modalità proxy, una singola lingua mancante significa che non ha ancora un hostname attivo. Vedi Astro con sottodomini linguistici.

Una modifica nella dashboard non viene mostrata

Causa. Il push su /_universally/revalidate non ha raggiunto il tuo server e il polling non è ancora avvenuto. Con revalidateSeconds impostato su 0 e un endpoint irraggiungibile, la modifica non arriva mai. Correzione. Attendi fino a revalidateSeconds (60 per impostazione predefinita). Per modifiche istantanee, rendi https://{tuo dominio}/_universally/revalidate raggiungibile da internet. Con diverse istanze del server, le altre si aggiornano tramite polling. Vedi Distribuisci un sito Astro con Universally.

Un sito statico non mostra nuove stringhe o modifiche

Causa. Una build statica è HTML su disco. Non ha polling né endpoint di push. Correzione. Ricompila. Quando il log di build dice N new strings translated. Rebuild to include them., compila ancora una volta, poi distribuisci.

Ogni pagina rimane nella lingua di origine

Causa. Il progetto ha utilizzato le sue parole prepagate, quindi Universally restituisce solo le stringhe che già possiede. Il log dice universally: word limit reached, {variant} keeps serving source text. Correzione. Aggiungi parole al progetto. Le stringhe già tradotte continuano ad essere servite nel frattempo, e quelle mancanti vengono nuovamente segnalate al loro prossimo rendering. Vedi Limiti di utilizzo e Traccia il tuo utilizzo.

L'endpoint di push restituisce 401

Causa. La firma non corrisponde alla metà privata della chiave sul tuo server, o il ts del corpo è più vecchio di 5 minuti rispetto all'orologio del tuo server. Una chiave rigenerata causa questo fino a quando non ridistribuisci. Correzione. Imposta la chiave corrente sull'host e ridistribuisci, e controlla l'orologio del server. Il formato completo è in Opzioni di integrazione Astro.

Lo script dello switcher è mancante

Causa. È impostato switcher: false, o la chiave non ha una metà pubblica (una chiave sk_). Il secondo caso registra un avviso. Correzione. Rimuovi switcher: false, o sostituisci la chiave con quella da 64 caratteri.

Ancora bloccato

Contatta il supporto con il dominio del tuo progetto, la tua versione di Astro, l'impostazione output e ogni riga universally: dal log del server.