Help us improve
Share bugs, ideas, or general feedback.
From antigravity-awesome-skills
Audits, validates, and generates hreflang implementations for international SEO on multilingual/multiregional sites. Checks self-referencing tags, bidirectional return links, x-default, ISO language/region codes, canonical alignment, and protocol consistency.
npx claudepluginhub sickn33/antigravity-awesome-skills --plugin antigravity-awesome-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/antigravity-awesome-skills:seo-hreflang [url][url]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
- Use when validating or generating hreflang for multilingual or multiregional sites.
Validates hreflang implementations, detects common mistakes (missing return tags, incorrect codes), and generates correct tags for HTML, headers, or sitemaps.
Audits, validates, and generates hreflang tags for international SEO across HTML link tags, HTTP headers, and XML sitemaps for multi-language/region sites.
Validates hreflang implementations and generates correct tags for multi-language/region sites. Checks self-referencing, return tags, x-default, language/region codes, canonical alignment, protocol consistency, and cross-domain support.
Share bugs, ideas, or general feedback.
Validate existing hreflang implementations or generate correct hreflang tags for multi-language and multi-region sites. Supports HTML, HTTP header, and XML sitemap implementations.
en, fr, de, ja)eng instead of en (ISO 639-2, not valid for hreflang)jp instead of ja (incorrect code for Japanese)zh without region qualifier (ambiguous; use zh-Hans or zh-Hant)en-US, en-GB, pt-BR)language-REGION (lowercase language, uppercase region)en-uk instead of en-GB (UK is not a valid ISO 3166-1 code)es-LA (Latin America is not a country; use specific countries)rel=canonical pointing elsewhere, hreflang on that page is ignored| Issue | Severity | Fix |
|---|---|---|
| Missing self-referencing tag | Critical | Add hreflang pointing to same page URL |
| Missing return tags (A→B but no B→A) | Critical | Add matching return tags on all alternates |
| Missing x-default | High | Add x-default pointing to fallback/selector page |
Invalid language code (e.g., eng) | High | Use ISO 639-1 two-letter codes |
Invalid region code (e.g., en-uk) | High | Use ISO 3166-1 Alpha-2 codes |
| Hreflang on non-canonical URL | High | Move hreflang to canonical URL only |
| HTTP/HTTPS mismatch in URLs | Medium | Standardize all URLs to HTTPS |
| Trailing slash inconsistency | Medium | Match canonical URL format exactly |
| Hreflang in both HTML and sitemap | Low | Choose one method (sitemap preferred for large sites) |
| Language without region when needed | Low | Add region qualifier for geo-targeted content |
Best for: Sites with <50 language/region variants per page.
<link rel="alternate" hreflang="en-US" href="https://example.com/page" />
<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />
Place in <head> section. Every page must include all alternates including itself.
Best for: Non-HTML files (PDFs, documents).
Link: <https://example.com/page>; rel="alternate"; hreflang="en-US",
<https://example.com/fr/page>; rel="alternate"; hreflang="fr",
<https://example.com/page>; rel="alternate"; hreflang="x-default"
Set via server configuration or CDN rules.
Best for: Sites with many language variants, cross-domain setups, or 50+ pages.
See Hreflang Sitemap Generation section below.
| Method | Best For | Pros | Cons |
|---|---|---|---|
| HTML link tags | Small sites (<50 variants) | Easy to implement, visible in source | Bloats <head>, hard to maintain at scale |
| HTTP headers | Non-HTML files | Works for PDFs, images | Complex server config, not visible in HTML |
| XML sitemap | Large sites, cross-domain | Scalable, centralized management | Not visible on page, requires sitemap maintenance |
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<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="de" href="https://example.de/page" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
</url>
<url>
<loc>https://example.com/fr/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="de" href="https://example.de/page" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
</url>
</urlset>
Key rules:
xmlns:xhtml namespace declaration<url> entry must include ALL language alternates (including itself)<url> entry with its own full set| Language | URL | Self-Ref | Return Tags | x-default | Status |
|---|---|---|---|---|---|
| en-US | https://... | ✅ | ✅ | ✅ | ✅ |
| fr | https://... | ❌ | ⚠️ | ✅ | ❌ |
| de | https://... | ✅ | ❌ | ✅ | ❌ |
<link> tags (if HTML method chosen)hreflang-sitemap.xml (if sitemap method chosen)| Scenario | Action |
|---|---|
| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again. |
| No hreflang tags found | Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method. |
| Invalid language/region codes detected | List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement. |