Dépannage de l'intégration Astro

La plupart des problèmes avec l'intégration Astro se manifestent par une page qui reste dans votre langue source ou une URL de langue qui renvoie une erreur 404. Le journal du serveur indique la cause de la plupart d'entre eux, et chaque avertissement est enregistré une fois.

Vérifiez d'abord les bases

1. Le serveur de build ou de développement démarre. S'il échoue avec "set UNIVERSALLY_API_KEY in .env or pass apiKey in the integration options", la clé est manquante. Placez-la dans .env à côté de astro.config.mjs, ou dans l'environnement où le build s'exécute. Sur Node antérieur à la version 20.12, les fichiers .env sont ignorés, utilisez donc l'environnement.
2. La clé est celle de 64 caractères de la page Configuration ou des Paramètres de l'API du projet. Une clé pk_ entraîne l'échec de l'appel des langues et du build.
3. Le commutateur Activer pour la langue est activé dans Toutes les langues.
4. Le texte passe par t(). Rien en dehors de t() n'est traduit.

Le premier rendu affiche le texte source

Cause. La chaîne n'avait pas encore de traduction. Elle est signalée à Universally après la réponse, et traduite en arrière-plan. Correction. Rechargez après une seconde ou deux. Une chaîne manquante est signalée à nouveau lors de son prochain rendu, elle arrive donc lors d'une requête ultérieure. Voir Mises à jour des traductions dans Astro.

Une langue renvoie une erreur 404 après son ajout

Cause. Les langues sont lues une fois, lorsque votre configuration Astro s'exécute. Une langue ajoutée ou activée par la suite n'est pas une route dans le build en cours. Correction. Redémarrez le serveur de développement, ou reconstruisez et redéployez.

Si la langue était présente mais que son catalogue n'a pas pu être chargé, le journal affiche universally: could not preload ..., et cette langue n'est pas retentée avant le redémarrage. Corrigez la cause et redémarrez.

Une seule chaîne reste non traduite pendant que les autres le sont

Cause. Le texte source est la clé, et il ne correspond pas à la chaîne source dans le tableau de bord. Un espace supplémentaire, un mot modifié, ou une ponctuation différente en font une chaîne différente. Une URL à l'intérieur de la chaîne en fait une clé différente sur chaque page. Correction. Comparez l'argument de t() avec la chaîne source sur l'écran Traductions, caractère par caractère. Gardez <a> en dehors de t(). Voir Traduire les pages dans Astro.

Aucun lien hreflang dans le HTML

Cause. site n'est pas défini dans astro.config.mjs, donc aucune URL absolue ne peut être construite. Le journal indique "site is not set in your Astro config, so no hreflang links were rendered." Correction. Définissez site sur votre domaine, par exemple site: 'https://example.com'. Vérifiez également que <UniversallyHead /> se trouve à l'intérieur de <head> dans votre mise en page. t(), href() et le sélecteur fonctionnent dans les deux cas. Voir les balises hreflang.

En mode proxy, une seule langue manquante signifie qu'elle n'a pas encore d'hôte actif. Voir Astro avec des sous-domaines linguistiques.

Une modification du tableau de bord ne s'affiche pas

Cause. Le push vers /_universally/revalidate n'a pas atteint votre serveur, et le polling n'a pas encore eu lieu. Avec revalidateSeconds à 0 et un point de terminaison inaccessible, la modification n'arrive jamais. Correction. Attendez jusqu'à revalidateSeconds (60 par défaut). Pour des modifications instantanées, rendez https://{votre domaine}/_universally/revalidate accessible depuis Internet. Avec plusieurs instances de serveur, les autres rattrapent par polling. Voir Déployer un site Astro avec Universally.

Un site statique n'affiche pas de nouvelles chaînes ou modifications

Cause. Une build statique est du HTML sur disque. Elle n'a pas de polling et pas de point de terminaison push. Correction. Reconstruire. Lorsque le journal de build indique N nouvelles chaînes traduites. Reconstruire pour les inclure., reconstruisez une fois de plus, puis déployez.

Chaque page reste dans la langue source

Cause. Le projet a utilisé ses mots prépayés, donc Universally ne renvoie que les chaînes qu'il détient déjà. Le journal indique universally: word limit reached, {variant} keeps serving source text. Correction. Ajoutez des mots au projet. Les chaînes déjà traduites continuent d'être servies entre-temps, et celles qui manquent sont signalées à nouveau lors de leur prochain rendu. Voir Limites d'utilisation et Suivre votre utilisation.

Le point de terminaison push renvoie 401

Cause. La signature ne correspond pas à la moitié privée de la clé sur votre serveur, ou le ts du corps est supérieur à 5 minutes par rapport à l'horloge de votre serveur. Une clé régénérée provoque cela jusqu'à ce que vous redéployiez. Correction. Définissez la clé actuelle sur votre hôte et redéployez, et vérifiez l'horloge du serveur. Le format complet se trouve dans Options d'intégration Astro.

Le script du sélecteur est manquant

Cause. switcher: false est défini, ou la clé n'a pas de moitié publique (une clé sk_). Le second cas enregistre un avertissement. Correction. Supprimez switcher: false, ou remplacez la clé par celle de 64 caractères.

Toujours bloqué

Contactez le support avec le domaine de votre projet, votre version d'Astro, votre paramètre output, et chaque ligne universally: du journal du serveur.