seo-hreflang

Validate hreflang implementations and generate corrected tags for HTML, HTTP headers, and XML sitemaps.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/avalonreset/gemini-seo --skill seo-hreflang-avalonreset
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: seo-hreflang
Source: https://github.com/avalonreset/gemini-seo/tree/main/skills/seo-hreflang
Command: npx skills add https://github.com/avalonreset/gemini-seo --skill seo-hreflang-avalonreset

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents international SEO failures by ensuring hreflang sets are complete, valid, and aligned with canonical URLs so search engines can correctly map language and region alternatives.

Core Features & Use Cases

  • Hreflang validation: checks for missing self-referencing tags, missing return tags (full bidirectional mesh), and missing or incorrect x-default fallbacks.
  • Code and URL correctness: validates ISO 639-1 language codes, ISO 3166-1 Alpha-2 region codes, protocol consistency (HTTP/HTTPS), trailing-slash consistency, and that hreflang appears only on canonical URLs.
  • Implementation outputs: generates ready-to-use hreflang snippets for HTML link tags, HTTP Link headers, or XML sitemap xhtml:link blocks, plus structured reporting recommendations.

Quick Start

Run the hreflang audit against your site URL or local folder to get a validation report and hreflang implementation recommendations.

Frequently Asked Questions about seo-hreflang

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I validate hreflang tags for international SEO?

Hreflang validation checks for missing self-referencing alternates, verifies full bidirectional return tag meshes, confirms x-default fallback placement, and flags ISO code or URL mismatches to ensure search engines correctly map international content.

What is the correct format for hreflang language and region codes?

Correct hreflang code format uses ISO 639-1 language codes and ISO 3166-1 Alpha-2 region codes. Strict validation checks these formats alongside protocol consistency and trailing-slash alignment to prevent international SEO targeting failures.

How do I generate hreflang tags for an XML sitemap?

Generate hreflang XML sitemap entries by producing ready-to-use xhtml:link blocks. The Skill outputs implementation-ready snippets for XML sitemaps, HTML link tags, and HTTP Link headers, ensuring correct multi-language URL alternates.

Why do my hreflang return tags keep failing validation?

Hreflang return tags fail validation when bidirectional relationships are incomplete, meaning alternate URLs do not link back to each other. Missing return tags break the full mesh required for search engines to confidently map language and region alternatives.

Can I use hreflang tags on non-canonical URLs?

Hreflang tags must appear only on canonical URLs. Validation enforces strict canonical alignment, verifying protocol consistency such as HTTP versus HTTPS and trailing-slash uniformity, ensuring search engines correctly parse international alternate URLs.

How do I set an x-default fallback for multi-region sites?

Set an x-default fallback by validating its correct placement within your hreflang tag sets for multi-region sites. This catches missing or incorrect fallbacks, ensuring search engines route unmatched language or region visitors to the correct default page.