georgekhananaev/seo-hreflang
.claude/skills/claude-seo/skills/seo-hreflang/SKILL.md
Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang implementations. Use when user says "hreflang", "i18n SEO", "international SEO", "multi-language", "multi-region", or "language tags".
$ install --global
skillsauthnpx skillsauth add georgekhananaev/claude-skills-vault seo-hreflangInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 15, 2026, 11:33 PM187.8s1 file scanned
SKILL.md
- name:
- seo-hreflang
- description:
- >
Hreflang & International SEO
Validate existing hreflang implementations or generate correct hreflang tags for multi-language and multi-region sites. Supports HTML, HTTP header, and XML sitemap implementations.
Validation Checks
1. Self-Referencing Tags
- Every page must include an hreflang tag pointing to itself
- The self-referencing URL must exactly match the page's canonical URL
- Missing self-referencing tags cause Google to ignore the entire hreflang set
2. Return Tags
- If page A links to page B with hreflang, page B must link back to page A
- Every hreflang relationship must be bidirectional (A→B and B→A)
- Missing return tags invalidate the hreflang signal for both pages
- Check all language versions reference each other (full mesh)
3. x-default Tag
- Required: designates the fallback page for unmatched languages/regions
- Typically points to the language selector page or English version
- Only one x-default per set of alternates
- Must also have return tags from all other language versions
4. Language Code Validation
- Must use ISO 639-1 two-letter codes (e.g.,
en,fr,de,ja) - Common errors:
enginstead ofen(ISO 639-2, not valid for hreflang)jpinstead ofja(incorrect code for Japanese)zhwithout region qualifier (ambiguous — usezh-Hansorzh-Hant)
5. Region Code Validation
- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g.,
en-US,en-GB,pt-BR) - Format:
language-REGION(lowercase language, uppercase region) - Common errors:
en-ukinstead ofen-GB(UK is not a valid ISO 3166-1 code)es-LA(Latin America is not a country — use specific countries)- Region without language prefix
6. Canonical URL Alignment
- Hreflang tags must only appear on canonical URLs
- If a page has
rel=canonicalpointing elsewhere, hreflang on that page is ignored - The canonical URL and hreflang URL must match exactly (including trailing slashes)
- Non-canonical pages should not be in any hreflang set
7. Protocol Consistency
- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)
- Mixed HTTP/HTTPS in hreflang sets causes validation failures
- After HTTPS migration, update all hreflang tags to HTTPS
8. Cross-Domain Support
- Hreflang works across different domains (e.g., example.com and example.de)
- Cross-domain hreflang requires return tags on both domains
- Verify both domains are verified in Google Search Console
- Sitemap-based implementation recommended for cross-domain setups
Common Mistakes
| 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 |
Implementation Methods
Method 1: HTML Link Tags
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.
Method 2: HTTP Headers
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.
Method 3: XML Sitemap (Recommended for large sites)
Best for: Sites with many language variants, cross-domain setups, or 50+ pages.
See Hreflang Sitemap Generation section below.
Method Comparison
| 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 |
Hreflang Generation
Process
- Detect languages: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
- Map page equivalents: Match corresponding pages across languages/regions
- Validate language codes: Verify all codes against ISO 639-1 and ISO 3166-1
- Generate tags: Create hreflang tags for each page including self-referencing
- Verify return tags: Confirm all relationships are bidirectional
- Add x-default: Set fallback for each page set
- Output: Generate implementation code (HTML, HTTP headers, or sitemap XML)
Hreflang Sitemap Generation
Sitemap with Hreflang
<?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:
- Include the
xmlns:xhtmlnamespace declaration - Every
<url>entry must include ALL language alternates (including itself) - Each alternate must appear as a separate
<url>entry with its own full set - Split at 50,000 URLs per sitemap file
Output
Hreflang Validation Report
Summary
- Total pages scanned: XX
- Language variants detected: XX
- Issues found: XX (Critical: X, High: X, Medium: X, Low: X)
Validation Results
| Language | URL | Self-Ref | Return Tags | x-default | Status | |----------|-----|----------|-------------|-----------|--------| | en-US | https://... | ✅ | ✅ | ✅ | ✅ | | fr | https://... | ❌ | ⚠️ | ✅ | ❌ | | de | https://... | ✅ | ❌ | ✅ | ❌ |
Generated Hreflang Tags
- HTML
<link>tags (if HTML method chosen) - HTTP header values (if header method chosen)
hreflang-sitemap.xml(if sitemap method chosen)
Recommendations
- Missing implementations to add
- Incorrect codes to fix
- Method migration suggestions (e.g., HTML → sitemap for scale)
Related Skills
georgekhananaev/pptx
documentation
VerifiedTrustedCommunity
Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks
20SKILL.mdUpdated Apr 15, 2026
georgekhananaev/pdf
tools
VerifiedTrustedCommunity
Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale.
20SKILL.mdUpdated Apr 15, 2026
georgekhananaev/md
development
VerifiedTrustedCommunity
Write clean, error-free markdown that IDEs and linters can parse without warnings. Use when writing documentation, README files, or skill files with code examples.
20SKILL.mdUpdated Apr 15, 2026
georgekhananaev/docx
development
VerifiedTrustedCommunity
Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks
20SKILL.mdUpdated Apr 15, 2026