Skill

seo-hreflang

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.

developer-tools

npx claudepluginhub agricidaniel/claude-seo --plugin claude-seo

Popularity

Stars

7,066

Forks

1,086

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/claude-seo:seo-hreflang [url]

User invocable

Model invocable

Inline context

Default effort

Argument hint[url]

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

Validate existing hreflang implementations or generate correct hreflang tags

Supporting Files

LICENSE.txtreferences/content-parity.mdreferences/cultural-profiles.mdreferences/locale-formats.mdreferences/machine-translation-qa.md

SKILL.md

256 lines · ~2.8k tokens

Similar Skills

seo-hreflang

Audits, validates, and generates hreflang implementations for international SEO. Checks self-referencing tags, bidirectional returns, x-default, language/region codes, canonical alignment, protocols, and cross-domain setups.

4 files

seo-dungeon

seo-hreflang

Audits, validates, and generates hreflang tags for international SEO across HTML link tags, HTTP headers, and XML sitemaps for multi-language/region sites.

seo

seo-hreflang

39.9k

Validates hreflang implementations, detects common mistakes (missing return tags, incorrect codes), and generates correct tags for HTML, headers, or sitemaps.

5 tools

antigravity-awesome-skills

Stats

LanguagePython

Stars7,066

Forks1,086

MaintenanceExcellent

Last CommitMay 25, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

Stats

Actions

Help us improve

Share bugs, ideas, or general feedback.

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.

seo-hreflang

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

Similar Skills

Help us improve

Help us improve

Find plugins for your project

seo-hreflang

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

Hreflang & International SEO

Validation Checks

1. Self-Referencing Tags

2. Return Tags

3. x-default Tag

4. Language Code Validation

5. Region Code Validation

6. Canonical URL Alignment

7. Protocol Consistency

8. Cross-Domain Support

Common Mistakes

Implementation Methods

Method 1: HTML Link Tags

Method 2: HTTP Headers

Method 3: XML Sitemap (Recommended for large sites)

Method Comparison

Hreflang Generation

Process

Hreflang Sitemap Generation

Sitemap with Hreflang

Output

Hreflang Validation Report

Summary

Validation Results

Generated Hreflang Tags

Recommendations

Cultural Adaptation Assessment

Content Parity Audit

Locale Format Validation

Reference Files

Error Handling

Similar Skills

Help us improve

Hreflang & International SEO

Validation Checks

1. Self-Referencing Tags

2. Return Tags

3. x-default Tag

4. Language Code Validation

5. Region Code Validation

6. Canonical URL Alignment

7. Protocol Consistency

8. Cross-Domain Support

Common Mistakes

Implementation Methods

Method 1: HTML Link Tags

Method 2: HTTP Headers

Method 3: XML Sitemap (Recommended for large sites)

Method Comparison

Hreflang Generation

Process

Hreflang Sitemap Generation

Sitemap with Hreflang

Output

Hreflang Validation Report

Summary

Validation Results

Generated Hreflang Tags

Recommendations

Cultural Adaptation Assessment

Content Parity Audit

Locale Format Validation

Reference Files

Error Handling