Seo HreflangSAFE

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for l

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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.4.2"
  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
- 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 canonic

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.