Skill

Review

Audit score 70

seo-hreflang

Q: Should I use HTML tags, HTTP headers, or XML sitemap?

For small sites (<50 variants per page), HTML link tags work fine. For large sites or cross-domain setups, XML sitemap is recommended and more scalable. HTTP headers are best for non-HTML files like PDFs.

agricidaniel/claude-seo

Audit, validate, and generate hreflang tags for multi-language and multi-region SEO.

Source View on skills.sh

What is seo-hreflang?

Detects hreflang mistakes, validates language/region codes against ISO standards, and generates correct implementations for HTML, HTTP headers, or XML sitemaps. Use when auditing international SEO or setting up multi-language sites.

Validates self-referencing tags, return tags, and x-default fallback configuration
Checks language codes (ISO 639-1) and region codes (ISO 3166-1) for correctness
Detects protocol mismatches, trailing slash inconsistencies, and canonical URL alignment issues
Generates hreflang tags in HTML link, HTTP header, or XML sitemap format
Identifies common mistakes like missing bidirectional relationships and invalid code formats
Produces validation reports with severity levels and specific fix recommendations

How to install seo-hreflang

npx skills add https://github.com/agricidaniel/claude-seo --skill seo-hreflang

Claude Code

Cursor

Windsurf

Cline

How to use seo-hreflang

1.Provide the URL of a page or site to audit, or specify the language variants and their URLs
2.The skill scans for hreflang tags in HTML head, HTTP headers, and sitemaps
3.Review the validation report showing which checks pass/fail (self-ref, return tags, x-default, codes)
4.Use generated hreflang tags in your preferred format: HTML link tags, HTTP headers, or XML sitemap
5.Implement fixes for critical issues (missing self-references, broken return tags, invalid codes)
6.Re-run validation after implementation to confirm all language variants are properly linked

Use cases

Good for

Audit existing hreflang implementations on multi-language sites to find critical errors
Generate correct hreflang tags when launching new language versions or regional variants
Validate cross-domain hreflang setups (e.g., example.com and example.de) for bidirectional consistency
Convert hreflang from HTML tags to XML sitemap format for large sites with 50+ language variants
Fix language code errors (e.g., 'eng' → 'en', 'jp' → 'ja', 'en-uk' → 'en-GB')

Who it's for

SEO specialists managing multi-language or multi-region websites
International site owners preparing for Google Search Console validation
Developers implementing hreflang during site migrations or HTTPS upgrades
Content teams coordinating language versions across multiple domains

seo-hreflang FAQ

What's the difference between language codes like 'en' vs 'eng' or 'ja' vs 'jp'?

Hreflang requires ISO 639-1 two-letter codes ('en', 'ja', 'fr'). Three-letter codes like 'eng' (ISO 639-2) and incorrect shortcuts like 'jp' are invalid and will be ignored by Google.

Do I need an x-default tag?

Yes. The x-default tag designates the fallback page for users whose language/region doesn't match any variant. It typically points to your language selector or English version and must have return tags from all other variants.

What happens if hreflang tags are missing return relationships?

If page A links to page B with hreflang but page B doesn't link back to page A, Google ignores the hreflang signal for both pages. All relationships must be bidirectional (full mesh).

Can I use hreflang on non-canonical URLs?

No. Hreflang tags must only appear on canonical URLs. If a page has rel=canonical pointing elsewhere, any hreflang on that page is ignored by Google.

Should I use HTML tags, HTTP headers, or XML sitemap?

For small sites (<50 variants per page), HTML link tags work fine. For large sites or cross-domain setups, XML sitemap is recommended and more scalable. HTTP headers are best for non-HTML files like PDFs.

Full instructions (SKILL.md)

Source of truth, from agricidaniel/claude-seo.

name: seo-hreflang description: > 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". user-invocable: true argument-hint: "[url]" license: MIT metadata: author: AgriciDaniel version: "2.2.0" category: seo

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:
- 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)

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-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)
- Region without language prefix

6. Canonical URL Alignment

Hreflang tags must only appear on canonical URLs
If a page has rel=canonical pointing 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:xhtml namespace 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 to sitemap for scale)

Cultural Adaptation Assessment

When analyzing a multi-language site, go beyond technical hreflang validation to assess whether the content is culturally adapted for each target market.

Load references/cultural-profiles.md for pre-built profiles (DACH, Francophone, Hispanic, Japanese).

Assessment steps:

Identify all language versions and their target markets
Load the relevant cultural profile(s)
Check CTAs match cultural expectations (direct vs indirect)
Check trust signals are locale-appropriate (certifications, legal pages)
Check for foreign brand references on localized pages
Check number/date/currency formatting consistency
Flag cultural adaptation issues as Medium severity

Output: Cultural Adaptation Score per language version (0-100) with specific findings.

Content Parity Audit

Command: /seo hreflang audit <directory-or-url>

Audit content parity across all language versions of a site or local content directory.

Load references/content-parity.md for the full parity matrix and scoring methodology.

What it checks:

Page existence across all declared languages
Section structure equivalence (H2/H3 count)
SEO element parity (title, meta, schema localization)
Word count ratio validation (DE should be 25-35% longer than EN, JA 10-25% shorter)
Freshness tracking (stale translations detected via timestamps)
Cultural marker scanning (foreign brands, wrong legal references, untranslated elements)

Output: Parity matrix table with per-page scores and prioritized action items.

Locale Format Validation

Load references/locale-formats.md for number, date, currency, address, and phone format reference tables per locale.

Checks:

Number format consistency (e.g., "1,000.00" should be "1.000,00" on de-DE pages)
Date format matches locale expectations
Currency symbols and placement correct for target market
Phone numbers use international format with correct country code

Reference Files

Load on-demand as needed (do NOT load all at startup):

references/cultural-profiles.md: DACH, Francophone, Hispanic, Japanese cultural adaptation profiles
references/locale-formats.md: Number, date, currency, address, phone format tables per locale
references/content-parity.md: Content parity audit methodology and scoring

Error Handling

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.
Cultural profile not available for language	Use the Default Profile checklist from cultural-profiles.md. Note that assessment is based on general guidelines, not a pre-built profile.
Content parity directory empty	Report that no content files were found. Suggest verifying the directory path or providing a URL for live site analysis.

Related skills

More from agricidaniel/claude-seo and the wider catalog.

seo-image-gen

agricidaniel/claude-seo

Generate SEO-optimized images (OG, hero, product, infographics) powered by Gemini via banana MCP.

2.1k installs

seo-images

agricidaniel/claude-seo

Analyze and optimize images for SEO: alt text, file size, format, lazy loading, SERP rankings, and metadata.

2.6k installs

seo-local

agricidaniel/claude-seo

Analyze local SEO for Google Business Profile optimization, NAP consistency, citations, reviews, and location-specific ranking factors.

2.3k installs

seo-maps

agricidaniel/claude-seo

Geo-grid rank tracking, GBP auditing, review intelligence, and cross-platform NAP verification for local SEO.

2.1k installs

seo-page

agricidaniel/claude-seo

Deep single-page SEO analysis covering on-page elements, content quality, technical meta tags, schema, images, and performance.

2.7k installs

seo-plan

agricidaniel/claude-seo

Strategic SEO planning with industry templates, competitive analysis, and phased implementation roadmap.

2.6k installs