/seo-hreflang

name: seo-hreflang
description: Hreflang and international SEO audit for multi-language and multi-region sites. Validates language-region codes, return tags, x-default, canonical alignment, and conflict detection across the per-URL HTML, the SE Ranking audit, and the XML sitemap. Use when the user asks "hreflang", "international SEO", "i18n", "language targeting", "x-default", "regional sites", or "multi-language SEO".

> Example output: [examples/seo-hreflang-airbnb-com-20260514/HREFLANG-REPORT.md](../../examples/seo-hreflang-airbnb-com-20260514/HREFLANG-REPORT.md)

Hreflang Audit

Adapted from `AgriciDaniel/claude-seo`'s `seo-hreflang` skill (MIT). Concept and validation rules originate there; this implementation is rebuilt against our backend (SE Ranking MCP + Firecrawl + WebFetch + Google APIs via `seo-google`).

Validate hreflang implementations on a multi-language or multi-region site. Surface SE Ranking audit-level hreflang issues, parse a sample of pages for the actual `<link rel="alternate" hreflang="…">` tags they emit, cross-check the sitemap, and produce one of three verdicts — **PASS**, **NEEDS-FIX**, or **BROKEN** — with a top-fixes table anchored in objective signals.

Prerequisites

• SE Ranking MCP server connected.
• Claude's `WebFetch` tool available (fallback when Firecrawl is unavailable).
• User provides: a target domain (e.g. `example.com`). Optional: explicit list of representative pages to inventory; explicit sitemap URL if not at `/sitemap.xml`.
• **Predecessor (recommended):** `seo-technical-audit` or `seo-sitemap` already run on this domain. Without an existing audit, the skill creates one (which costs significantly more credits).

Process

1. **Validate target & preflight.** See `skills/seo-firecrawl/references/preflight.md` for the canonical 3-stage preflight (credit balance, Firecrawl availability, Google APIs). Skill-specific notes:

• Normalise domain (strip protocol, trailing slash) before continuing.
• Estimated SE Ranking cost for this skill: ~5–10 SE Ranking credits for re-using an existing audit (up to ~3 Firecrawl credits for the per-URL inventory).
• Firecrawl: optional with WebFetch fallback, ~6 Firecrawl credits if available (hard cap). When available, step 4 (per-URL hreflang inventory) runs on homepage + 5 representative pages with `formats: ["rawHtml"]`. Without Firecrawl, step 4 falls back to WebFetch — coverage is degraded because WebFetch returns markdown only and silently strips `<link rel="alternate">` tags from `<head>`. Pass `--no-firecrawl` to force WebFetch even when Firecrawl is available.
• Google APIs: tier 1 (GSC) unlocks step 6 (GSC verification of hreflang-targeted alternates). See `skills/seo-google/references/cross-skill-integration.md` for the full enrichment contract.

2. **Find or refresh the audit** `DATA_listAudits` → `DATA_getAuditStatus`

• List audits for the domain. If a recent audit exists (<30 days), use it.
• If older than 30 days, run `DATA_recheckAudit` and wait for `done`.
• If none exists, ask the user before creating one with `DATA_createStandardAudit` — it consumes credits.

3. **Pull SE Ranking's hreflang findings** `DATA_getAuditReport` + `DATA_getAuditPagesByIssue`

• SE Ranking's audit catches hreflang errors directly — surface them first as ground truth.
• From `DATA_getAuditReport`, extract every issue with code or category matching `hreflang` (typical codes: `hreflang_no_return_tag`, `hreflang_invalid_lang_code`, `hreflang_conflict`, `hreflang_missing_x_default`, `hreflang_canonical_mismatch`, `hreflang_no_self_reference`).
• For each significant hreflang issue (count ≥ 1), call `DATA_getAuditPagesByIssue` to enumerate the affected URLs.
• Persist to `01-audit-hreflang-issues.md` and feed into `hreflang-issues.csv`.

4. **Per-URL hreflang tag inventory** `mcp__firecrawl-mcp__firecrawl_scrape` (preferred) / `WebFetch` (fallback)

• **Sample selection:** homepage + up to 5 representative pages from `DATA_getDomainPages` (sort by traffic descending; bias toward pages on different language paths if the URL structure exposes them — `/en/`, `/fr/`, `/de/`, etc.).
• **Firecrawl path** (1 credit per URL, ~6 total): call `firecrawl_scrape(url=..., formats=["rawHtml"])`. Pin `rawHtml` — the default `html` post-processing strips `<link rel="alternate">` on many sites. Parse every `<link rel="alternate" hreflang="…" href="…">` from the `<head>`. Capture: source URL, hreflang attribute, href, and whether it's self-referencing.
• **WebFetch fallback** (no Firecrawl): try fetching each URL and extracting hreflang from the markdown response. WebFetch frequently returns markdown that has stripped `<head>` link tags, so this path will under-report. Note in `HREFLANG-REPORT.md`: `Per-URL inventory: degraded coverage — Firecrawl not installed; some hreflang tags may be missed.`
• **Apply validation rules** (see references/validation-rules.md for the full list):
• **Self-referencing tag:** the page's own URL must appear in its own hreflang set.
• **Return tags:** every alternate link must reciprocate. If page A lists B as `fr`, page B must list A as `en` (or whichever).
• **x-default:** at least one alternate per set must use `hreflang="x-default"`.
• **Language-region code validation:** every value must be a valid ISO 639-1 language (optionally followed by `-` and an ISO 3166-1 Alpha-2 region). Common errors caught: `eng` (use `en`), `jp` (use `ja`), `en-uk` (use `en-GB`), `es-LA` (no such ISO region).
• **Conflict detection:** the same hreflang value (e.g. `de-DE`) appearing on multiple distinct URLs is a conflict — Google ignores conflicting sets.
• **Canonical alignment:** if the page has `<link rel="canonical">`, it must match the page's own URL (or its self-referencing hreflang URL). Hreflang on a non-canonical page is silently ignored by Google.
• **Protocol consistency:** all URLs in a set must share the same scheme (HTTPS pr