developer marketing skill risk: low

Hreflang SEO Validator and Generator

Validate existing hreflang implementations or generate correct hreflang tags for multi-language and multi-region sites using HTML, HTTP headers, or XML sitemaps, while performing c…

SKILL 5 files · 1 folder

SKILL.md

Download

---
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:
  - `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.

```html
<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
1. **Detect languages**: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
2. **Map page equivalents**: Match corresponding pages across languages/regions
3. **Validate language codes**: Verify all codes against ISO 639-1 and ISO 3166-1
4. **Generate tags**: Create hreflang tags for each page including self-referencing
5. **Verify return tags**: Confirm all relationships are bidirectional
6. **Add x-default**: Set fallback for each page set
7. **Output**: Generate implementation code (HTML, HTTP headers, or sitemap XML)

## Hreflang Sitemap Generation

### Sitemap with Hreflang
```xml
<?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:**
1. Identify all language versions and their target markets
2. Load the relevant cultural profile(s)
3. Check CTAs match cultural expectations (direct vs indirect)
4. Check trust signals are locale-appropriate (certifications, legal pages)
5. Check for foreign brand references on localized pages
6. Check number/date/currency formatting consistency
7. 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. |

REQUIRED CONTEXT

directory-or-url or site pages to audit

OPTIONAL CONTEXT

implementation method (HTML/HTTP/sitemap)
reference files for cultural profiles and formats

TOOLS REQUIRED

file_search

ROLES & RULES

Load references/cultural-profiles.md for pre-built profiles
Load references/content-parity.md for the full parity matrix and scoring methodology
Load references/locale-formats.md for number, date, currency, address, and phone format reference tables per locale
Load on-demand as needed (do NOT load all at startup)
Report the error clearly. Do not guess site structure
Suggest the user verify the URL and try again
Report the absence
Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method
List each invalid code with the correct replacement
Provide a corrected hreflang tag set ready to implement
Use the Default Profile checklist from cultural-profiles.md
Note that assessment is based on general guidelines, not a pre-built profile
Report that no content files were found
Suggest verifying the directory path or providing a URL for live site analysis

EXPECTED OUTPUT

Format

structured_report

Schema

markdown_sections · Summary, Validation Results, Generated Hreflang Tags, Recommendations, Cultural Adaptation Score, Parity matrix table

Constraints

include summary with counts and severity breakdown
include validation results table
include generated tags or sitemap XML when applicable
include recommendations and cultural/parity scores

SUCCESS CRITERIA

Validate existing hreflang implementations
Generate correct hreflang tags
Perform cultural adaptation assessment
Audit content parity across language versions
Validate locale formats

FAILURE MODES

URL unreachable
No hreflang tags found
Invalid language/region codes detected
Cultural profile not available for language
Content parity directory empty

EXAMPLES

Includes HTML link tags, HTTP headers, XML sitemap examples, common mistakes table, method comparison table, validation results table, and error handling table.

CAVEATS

Dependencies

references/cultural-profiles.md
references/content-parity.md
references/locale-formats.md
directory-or-url argument for /seo hreflang audit command

Missing context

How reference files are accessed or loaded in the runtime environment.
Input format for URLs or directories to analyze.

Ambiguities

Initial description field contains only ')' which appears erroneous.
Assumes external system commands like '/seo hreflang audit' without defining the interface.

QUALITY

OVERALL: 0.82
CLARITY: 0.80
SPECIFICITY: 0.90
REUSABILITY: 0.75
COMPLETENESS: 0.85

IMPROVEMENT SUGGESTIONS

Correct the malformed description field to something like 'Validate or generate hreflang tags for international SEO.'
Add explicit input parameters section for the audit command.

USAGE

Copy the prompt above and paste it into your AI of choice — Claude, ChatGPT, Gemini, or anywhere else you're working. Replace any placeholder sections with your own context, then ask for the output.