seo-hreflang

Files (6)

• LICENSE.txt
• SKILL.md
• content-parity.md · references/
• cultural-profiles.md · references/
• locale-formats.md · references/
• machine-translation-qa.md · references/

SKILL.md (first lines)

# 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
- Recommended when a selector/fallback URL exists: 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`)
- An **optional ISO 15924 script subtag** is the documented, official mechanism
  for script: `zh-Hant` (Traditional) / `zh-Hans` (Simplified). Script may
  combine with a region, e.g. `zh-Hans-US` is valid (language + script + region).
- Common errors:
  - `eng` instead of `en` (ISO 639-2, not valid for hreflang)
  - `jp` instead of `ja` (incorrect code for Japanese)
  - `zh` is valid but ambiguous for script-specific pages; prefer `zh-Hans` or `zh-Hant` when targeting a script

### 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)
- A **country code alone is invalid**, you cannot specify a region without a
  language (Google's own bad example is `be`, which is actually the Belarusian
  *language* code, not Belgium).
- Common errors:
  - `en-uk` instead of `en-GB` (UK is not a valid ISO 3166-1 region code)
  - `EU` / `UN` as a region (not valid ISO 3166-1 values)
  - `es-LA` (Latin America is not a country; use specific countries)
  - Region without language prefix

### 5b. Geo-targeting signal hierarchy
- Practical locale-signal heuristic: **ccTLD > hreflang annotations >
  server location/IP > addresses/language/currency/Business Profile**. Do not
  present this as a confirmed Google ranking order. hreflang is a
  **hint, not a directive**. Google **ignores** locational meta tags and
  HTML geotargeting attributes.
- The Search Console **International Targeting report and the manual
  country-targeting setting were removed in 2022**, do **not** recommend setting
  country targeting in GSC; hreflang is the remaining lever.

### 5c. Region-specific Search units (EEA, South Africa, Türkiye)
- Google documents Search experiences that exist only in certain regions
  (documentation added 2026-09-08; https://developers.google.com/search/docs/appearance/aggregator-features):
  - **EEA only:** aggregator units and supplier units (hotels, flights, ground
    transportation, products, and since 2026-09-18 local businesses), the
    ecosystem carousel, and job-site features.
  - **Türkiye:** places-site features (hotels, local businesses).
  - **South Africa:** a badge and refinement chip for travel, products, car
    hire, food delivery and ground transportation.
  - **Structured data carousels** in all three, with different query types.
  Eligibility and participation are documented per unit; they are not ranking
  signals.
- When a site serves those regions with hreflang variants, note in the report
  whether the business is an aggregator or a direct supplier and point to the
  regional documentation, so the client is not surprised by a different result
  layout in those markets.

### 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
- Use Google Search Console verification for monitoring or cross-site sitemap submission when needed
- 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 when fallback behavior is required | Medium | 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.

From AgriciDaniel/claude-seo, MIT.

More from AgriciDaniel/claude-seo