Solución de problemas de integración de Astro

La mayoría de los problemas con la integración de Astro se manifiestan como una página que permanece en tu idioma de origen o una URL de idioma que devuelve 404. El registro del servidor indica la causa de la mayoría de ellos, y cada advertencia se registra una vez.

Comprueba primero lo básico

1. El servidor de compilación o desarrollo se inicia. Si falla con "establecer UNIVERSALLY_API_KEY en .env o pasar apiKey en las opciones de integración", la clave falta. Colócala en .env junto a astro.config.mjs, o en el entorno en el que se ejecuta la compilación. En Node anterior a 20.12, los archivos .env se omiten, así que usa el entorno.
2. La clave es la de 64 caracteres de la página Configuración o Ajustes de API del proyecto. Una clave pk_ falla la llamada de idiomas y la compilación.
3. El interruptor "En vivo" del idioma está activado en Todos los idiomas.
4. El texto pasa por t(). Nada fuera de t() se traduce.

La primera renderización muestra el texto de origen

Causa. La cadena aún no tenía traducción. Se informa a Universally después de la respuesta y se traduce en segundo plano. Solución. Recarga después de uno o dos segundos. Una cadena omitida se informa nuevamente en su próxima renderización, por lo que llega en una solicitud posterior. Ver Actualizaciones de traducción en Astro.

Un idioma devuelve 404 después de que lo agregaste

Causa. Los idiomas se leen una vez, cuando se ejecuta tu configuración de Astro. Un idioma agregado o cambiado después no es una ruta en la compilación en ejecución. Solución. Reinicia el servidor de desarrollo, o recompila y redespliega.

Si el idioma estaba allí pero su catálogo no se pudo cargar, el registro muestra universally: could not preload ..., y ese idioma no se vuelve a intentar hasta el reinicio. Soluciona la causa y reinicia.

Una cadena permanece sin traducir mientras que el resto se traduce

Causa. El texto de origen es la clave, y no coincide con la cadena de origen en el panel. Un espacio adicional, una palabra cambiada o una puntuación diferente la convierten en una cadena diferente. Una URL dentro de la cadena la convierte en una clave diferente en cada página. Solución. Compara el argumento de t() con la cadena de origen en la pantalla Traducciones, carácter por carácter. Mantén <a> fuera de t(). Ver Traducir páginas en Astro.

No hay enlaces hreflang en el HTML

Causa. site no está configurado en astro.config.mjs, por lo que no se puede construir una URL absoluta. El registro dice "site is not set in your Astro config, so no hreflang links were rendered." Solución. Configura site a tu dominio, como site: 'https://example.com'. También verifica que <UniversallyHead /> esté dentro de <head> en tu diseño. t(), href() y el selector funcionan de cualquier manera. Ver etiquetas hreflang.

En modo proxy, un solo idioma faltante significa que aún no tiene un nombre de host activo. Ver Astro con subdominios de idioma.

Una edición del panel no se muestra

Causa. El envío a /_universally/revalidate no llegó a tu servidor y la sondeo aún no ha ocurrido. Con revalidateSeconds en 0 y un punto final inalcanzable, la edición nunca llega. Solución. Espera hasta revalidateSeconds (60 por defecto). Para ediciones instantáneas, haz que https://{tu dominio}/_universally/revalidate sea accesible desde internet. Con varias instancias de servidor, las otras se ponen al día mediante sondeo. Ver Despliega un sitio Astro con Universally.

Un sitio estático no muestra cadenas nuevas ni ediciones

Causa. Una compilación estática es HTML en disco. No tiene sondeo ni punto final de envío. Solución. Recompila. Cuando el registro de compilación diga N new strings translated. Rebuild to include them., compila una vez más, luego despliega.

Cada página permanece en el idioma de origen

Causa. El proyecto ha utilizado sus palabras prepagas, por lo que Universally solo devuelve las cadenas que ya tiene. El registro dice universally: word limit reached, {variant} keeps serving source text. Solución. Agrega palabras al proyecto. Las cadenas que ya están traducidas continúan sirviéndose mientras tanto, y las faltantes se informan nuevamente en su próximo renderizado. Ver Límites de uso y Rastrea tu uso.

El punto final de envío devuelve 401

Causa. La firma no coincide con la mitad privada de la clave en tu servidor, o la ts del cuerpo está a más de 5 minutos del reloj de tu servidor. Una clave regenerada causa esto hasta que redespliegas. Solución. Configura la clave actual en tu host y redespliega, y verifica el reloj del servidor. El formato completo está en Opciones de integración de Astro.

Falta el script del selector

Causa. Se establece switcher: false, o la clave no tiene mitad pública (una clave sk_). El segundo caso registra una advertencia. Solución. Elimina switcher: false, o reemplaza la clave con la de 64 caracteres.

Aún atascado

Contacta a soporte con el dominio de tu proyecto, tu versión de Astro, tu configuración de output y cada línea universally: del registro del servidor.