What validation checks does this skill run on hreflang implementations?

It runs eight checks: self-referencing tags (every page must reference itself with exact canonical URL match), bidirectional return tags (all hreflang relationships must be reciprocal), x-default fallback tag (exactly one per set with its own return tags), ISO 639-1 language code validity, ISO 3166-1 Alpha-2 region code validity, canonical URL alignment, protocol consistency (no mixed HTTP/HTTPS), and cross-domain support (requiring return tags and Search Console verification).

What are the three ways to implement hreflang and when should I use each?

HTML link tags work best for under 50 variants per page but bloat the ` ` at scale; HTTP headers are for non-HTML files like PDFs; XML sitemap is recommended for large or cross-domain sites and requires the `xmlns:xhtml` namespace with every URL entry listing the full alternate set including itself, split at 50,000 URLs per file.

What does this skill output after validating or generating hreflang?

It produces a Hreflang Validation Report showing pages scanned, language variants, issues ranked by severity, and a per-language status table for self-references, return tags, and x-default tags, plus generated implementation code in your chosen format (HTML, HTTP headers, or XML sitemap) with specific fix and migration recommendations.

What happens if the skill finds no hreflang tags on a site?

Instead of assuming misconfiguration, it checks for other internationalization signals like subdirectories, subdomains, or ccTLDs, and recommends an appropriate implementation method based on your site structure.

What are common hreflang mistakes this skill catches?

It identifies critical issues like missing self-references or bidirectional return tags, and catches common code errors such as `eng` instead of `en`, `jp` instead of `ja`, `en-uk` instead of `en-GB`, and invalid region codes like `es-LA`.

Skill

Validate and Generate Hreflang Tags

Name: Hreflang & International SEO
Availability: OnlineOnly
Author: Antigravity

A skill for validating and generating hreflang tags across HTML, HTTP headers, and XML sitemaps for multilingual sites.

Get skill

Antigravity

Own this? Claim it

Spark score

out of 100

Updated last month

Version 13.4.0

Add to Favorites

Why it matters

Ensure your multilingual and multiregional website is correctly configured for international SEO. This asset validates existing hreflang implementations or generates new ones to improve search engine visibility across different locales.

Outcomes

What it gets done

Validate self-referencing and return hreflang tags.

Check for correct x-default tag implementation.

Verify language and region code accuracy (ISO 639-1, ISO 3166-1).

Generate hreflang tags for HTML, HTTP headers, or XML sitemaps.

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-seo-hreflang | bash

Overview

Hreflang & International SEO

A skill for validating and generating hreflang tags across HTML, HTTP header, and XML sitemap implementations, with severity-ranked issue detection. Use it for multilingual/multiregional hreflang validation or generation specifically, not for general international SEO strategy beyond language-tag correctness.

What it does

This skill validates existing hreflang implementations or generates correct hreflang tags for multi-language and multi-region sites, across HTML link tags, HTTP headers, and XML sitemap implementations. It runs eight validation checks: self-referencing tags (every page must reference itself, exactly matching its canonical URL), return tags (every hreflang relationship must be bidirectional across the full mesh of language versions), the x-default fallback tag (exactly one per alternate set, itself requiring return tags), language code validity (ISO 639-1 two-letter codes, catching errors like eng instead of en or jp instead of ja), region code validity (ISO 3166-1 Alpha-2, catching errors like en-uk instead of en-GB or es-LA which is not a valid country code), canonical URL alignment (hreflang only valid on canonical URLs, exact match including trailing slashes), protocol consistency (no mixed HTTP/HTTPS within a set), and cross-domain support (requiring return tags and Search Console verification on both domains). It ranks common mistakes by severity from Critical (missing self-reference or return tags) to Low (redundant hreflang in both HTML and sitemap). It compares the three implementation methods - HTML link tags (best under 50 variants per page, but bloats <head> at scale), HTTP headers (for non-HTML files like PDFs), and XML sitemap (recommended for large or cross-domain sites, requiring the xmlns:xhtml namespace, every URL entry listing the full alternate set including itself, and splitting at 50,000 URLs per sitemap file) - and follows a seven-step generation process: detect languages, map page equivalents, validate codes, generate self-referencing tags, verify bidirectional return tags, add x-default, and output in the chosen format.

When to use - and when NOT to

Use it when validating or generating hreflang for a multilingual or multiregional site, or when the user raises international SEO, language tags, x-default, or hreflang issues specifically. On an unreachable URL it reports the error rather than guessing site structure; if no hreflang tags are found, it checks for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommends an appropriate implementation method rather than assuming misconfiguration; invalid codes are listed individually with corrected replacements.

Inputs and outputs

Inputs: a target site's URL(s) and language/region structure, or an existing hreflang implementation to validate.
Outputs: a Hreflang Validation Report (pages scanned, language variants, issues by severity, a per-language self-ref/return-tag/x-default status table) plus generated implementation code in the chosen format (HTML link tags, HTTP header values, or a hreflang-sitemap.xml) and specific fix/migration recommendations.

<url>
  <loc>https://example.com/page</loc>
  <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
  <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
  <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
</url>

Who it's for

SEO practitioners and developers managing multilingual or multiregional sites who need to validate existing hreflang setups or generate correct, bidirectional tags in the right format for their site's scale.

FAQ

Common questions

Discussion