Audit canonical and hreflang in an Astro website

A bilingual website can build successfully while its alternate-language links disagree. This walkthrough uses Aura Logic Site Audit to reproduce a missing hreflang return annotation and a broken internal link, then verify a corrected version. The fixture is deliberately small: two pages, one sitemap and no customer data.

Install and run the local example

Use Node.js 22.22.1 or newer; we recommend Node 24. The project is MIT licensed and installed from GitHub. There is no published npm release yet.

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

Leave the fixture running. In a second terminal, from the same directory:

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

The command exits with code 1 because the fixture contains intentional errors. Open the JSON even though the command did not exit successfully. Reports are ignored in the auditor repository; check your own project’s ignore rules before storing reports there.

Read evidence rather than just totals

The baseline has two parsed HTML pages and three error findings. BROKEN_LINK identifies the home page linking to /missing-page. HTTP_ERROR records the same destination’s 404 response. These two observations represent one failed destination, not two independent repairs.

HREFLANG_RETURN_MISSING identifies a different defect: the English home page declares the Spanish version, but the Spanish page does not declare the English return URL. Both pages have their own canonical, so the return annotation is the relevant source change.

Check schemaVersion, complete, summary and each finding’s code, url and optional target. A report with complete: false has gaps. An informational finding is not automatically a defect. Save the exact command alongside your notes: crawl options are not included in the JSON.

Understand the corrected head

In this fixture, the English page has a self-referencing canonical and both language alternates:

<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/" />

The Spanish page uses the same alternate set, with its own 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/" />

Google’s localized-page guidance describes self-reference, return links and fully qualified alternate URLs. An x-default URL is optional and can identify a fallback page. Canonical and hreflang express different relationships; pointing all translations to the English canonical is not the repair for a missing return annotation.

Verify the corrected fixture

Stop the first server with Ctrl+C and restart it in corrected mode:

node examples/demo-site.mjs --fixed

In the second terminal, repeat the audit with the same limits and a separate output:

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

This mode restores reciprocal annotations and removes the intentional broken link. The follow-up should exit 0, with two pages and no error or warning findings. Compare findings by (code, url, target), rather than timestamps or array positions. The destination removed from the link graph no longer requires fetching, so the request count can decrease. A disappeared finding alone is insufficient if the affected page was excluded or the audit became partial.

The corrected fixture demonstrates the desired HTML. To repair your own Astro project, inspect the .astro layout and the route or content registry that produces that HTML. Map real translations explicitly, use the production site origin, and preserve the site’s trailing-slash convention. Avoid editing generated dist/ files: the next build replaces them.

Apply the workflow to your website

Build and preview your site, then run the CLI against its preview origin. For Astro’s default preview port:

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

Run this from the auditor repository while your website preview is running separately. Adjust the URL to match the actual preview port. A canonical pointing to production from a local preview can produce an origin-related diagnostic; compare with the production environment before deciding that declaration is wrong.

The AI workflow kit provides prompts for triage, one focused repair and verification. Redact private URLs or query strings before sharing JSON. Review the proposed diff and check the generated head yourself.

Know what this audit cannot prove

This version fetches HTML and checks same-origin links. It does not render client-side JavaScript, inspect external alternate destinations, or read hreflang from XML extensions or HTTP headers. It cannot show which canonical Google selected or whether a page is indexed. Read the full check limitations.

For a real site, keep evidence from the build, HTTP responses and follow-up audit. Use Search Console for Google’s indexing observations. Resolving a supported technical defect is a verifiable improvement; a ranking increase is a separate question.