Cómo auditar canonical y hreflang en una web Astro

Una web bilingüe puede compilar correctamente aunque sus enlaces entre idiomas no coincidan. Usaremos Aura Logic Site Audit para reproducir un hreflang sin retorno y un enlace interno roto, y comprobar después la versión corregida. La demo tiene dos páginas, un sitemap y ningún dato de clientes.

Instala y ejecuta el ejemplo local

Necesitas Node.js 22.22.1 o superior; recomendamos Node 24. El proyecto tiene licencia MIT y se instala desde GitHub. Todavía no hay una versión publicada en npm.

git clone https://github.com/Traka-Dev/auralogic-site-audit.git
cd auralogic-site-audit
npm ci
npm run build
node examples/demo-site.mjs

Deja la demo ejecutándose. En otra terminal, desde el mismo directorio:

node dist/cli.js http://127.0.0.1:4329 --max-pages 200 --max-requests 500 --json --output reports/before.json

El comando termina con código 1 porque hay errores intencionales. Abre el JSON aunque la ejecución no termine con éxito. El repositorio del auditor ignora los reportes; comprueba el .gitignore de tu propio proyecto antes de guardarlos allí.

Lee la evidencia, además del total

La primera auditoría analiza dos páginas HTML y registra tres hallazgos de error. BROKEN_LINK señala que la portada enlaza a /missing-page. HTTP_ERROR registra el 404 de ese mismo destino. Son dos observaciones sobre un enlace fallido, no dos correcciones independientes.

HREFLANG_RETURN_MISSING describe otro problema: la portada inglesa declara la versión española, pero esta no devuelve la referencia a la inglesa. Ambas tienen su propio canonical; la corrección relevante es restaurar el enlace alternativo de retorno.

Comprueba schemaVersion, complete, summary y los campos code, url y target de cada hallazgo. complete: false indica que quedan huecos de cobertura. Un hallazgo informativo no es necesariamente un error. Anota el comando exacto: sus límites de rastreo no se guardan en el JSON, así que conviene que guardes cómo lo ejecutaste.

Entiende el head corregido

En esta demo, la página inglesa tiene un canonical que apunta a sí misma y las dos variantes de idioma:

<link rel="canonical" href="http://127.0.0.1:4329/" />
<link rel="alternate" hreflang="en" href="http://127.0.0.1:4329/" />
<link rel="alternate" hreflang="es" href="http://127.0.0.1:4329/es/" />

La página española usa el mismo conjunto de alternates, con su propio canonical:

<link rel="canonical" href="http://127.0.0.1:4329/es/" />
<link rel="alternate" hreflang="en" href="http://127.0.0.1:4329/" />
<link rel="alternate" hreflang="es" href="http://127.0.0.1:4329/es/" />

La guía de Google sobre páginas localizadas explica la autorreferencia, los enlaces de retorno y las URLs absolutas. x-default es opcional y puede identificar una página de fallback. Canonical y hreflang expresan relaciones distintas: hacer que todas las traducciones tengan canonical hacia el inglés no corrige un retorno ausente.

Comprueba la demo corregida

Detén el primer servidor con Ctrl+C y reinícialo en modo corregido:

node examples/demo-site.mjs --fixed

En la otra terminal, repite la auditoría con los mismos límites y un archivo distinto:

node dist/cli.js http://127.0.0.1:4329 --max-pages 200 --max-requests 500 --json --output reports/after.json

Este modo restaura las referencias recíprocas y elimina el enlace roto intencional. Debe terminar con código 0, dos páginas y ningún hallazgo de error o advertencia. Compara los hallazgos por (code, url, target), no por fecha ni posición en la lista. Al quitar el destino roto del grafo de enlaces, deja de ser necesario consultarlo y puede bajar el número de peticiones. Que desaparezca un hallazgo no basta si la página afectada quedó fuera del rastreo o la auditoría pasó a ser parcial.

La demo corregida muestra el HTML esperado. En tu proyecto Astro, revisa el layout .astro y el registro de rutas o contenido que lo genera. Mapea traducciones reales de forma explícita, usa el origen de producción y respeta la convención de barra final. No edites dist/: el siguiente build reemplazará esos archivos.

Aplica el proceso a tu web

Compila tu web, abre su preview y ejecuta la CLI contra ese origen. Para el puerto habitual del preview de Astro:

node dist/cli.js http://localhost:4321 --max-pages 200 --max-requests 500 --json --output reports/site.json

Ejecuta el comando desde el repositorio del auditor, mientras la web corre por separado. Ajusta el puerto a tu entorno. Un canonical que apunta a producción desde un preview local puede generar un diagnóstico relacionado con el origen; contrástalo con producción antes de concluir que esa declaración es incorrecta.

El kit de trabajo con IA incluye prompts para clasificar, corregir una causa y verificar. Elimina URLs privadas o parámetros sensibles antes de compartir el JSON. Revisa el diff propuesto e inspecciona el head generado.

Qué no demuestra esta auditoría

Esta versión obtiene HTML y comprueba enlaces del mismo origen. No renderiza JavaScript del cliente, inspecciona destinos alternativos externos ni lee hreflang en extensiones XML o cabeceras HTTP. Tampoco puede decir qué canonical eligió Google o si una página está indexada. Consulta el alcance completo.

En una web real, conserva la evidencia del build, las respuestas HTTP y la auditoría posterior. Usa Search Console para observar la indexación en Google. Resolver un defecto técnico compatible con el auditor es comprobable; una mejora de posiciones requiere evidencia distinta.