| name | seo-hreflang |
| description | Hreflang and international SEO — validate existing hreflang implementations (self-ref, return tags, x-default, language/region codes) and generate correct HTML/HTTP-header/sitemap implementations for multi-language and multi-region sites. Also audits cultural adaptation, content parity, locale formatting, and machine-translation quality across language versions. |
| allowed-tools | Read, Write, Glob, Grep |
SEO Hreflang — International SEO Validation & Generation
A hreflang set with one broken return tag invalidates the whole set — Google treats it as a hint, not a directive, and a hint it can't trust it drops.
When this skill activates
Implicit: "hreflang", "i18n SEO", "international SEO", "multi-language site", "multi-region site", "language tags", "x-default".
Explicit: "Use the seo-hreflang skill to [task]."
Routed from: [[seo]] orchestrator, for sites detected as multi-region/multi-language; /mk:seo hreflang audit <directory-or-url>.
Scope
Covers:
- Hreflang validation: self-referencing tags, return-tag bidirectionality, x-default, language/region code correctness, canonical alignment, protocol consistency, cross-domain setups.
- Hreflang generation: HTML
<link> tags, HTTP headers, XML sitemap entries.
- Cultural adaptation assessment (CTAs, trust signals, legal pages, foreign-brand references) per target market.
- Content parity audit across language versions (structure, SEO elements, word-count ratio, freshness).
- Locale format validation (number/date/currency/address/phone) and machine-translation QA flags.
Does NOT cover:
- Broader technical SEO (crawl budget, Core Web Vitals, site architecture unrelated to i18n) → [[seo-technical]].
- Local/regional business targeting (Google Business Profile, NAP consistency, local pack) → [[seo-local]].
- Writing the localized content itself → [[seo-content]].
Validation checks
1. Self-referencing tags
Every page must include a hreflang tag pointing to itself, and that self-referencing URL must exactly match the page's canonical URL. Missing it causes Google to ignore the entire hreflang set.
2. Return tags
If page A links to page B with hreflang, B must link back to A — every relationship bidirectional (full mesh across all language versions). A missing return tag invalidates the signal for both pages.
3. x-default
Recommended whenever a selector/fallback URL exists: designates the fallback page for unmatched languages/regions (typically the language selector or English version). Only one x-default per alternate set, and it needs return tags from every other version too.
4. Language code validation
- Must use ISO 639-1 two-letter codes (
en, fr, de, ja).
- An optional ISO 15924 script subtag is the documented mechanism for script:
zh-Hant (Traditional) / zh-Hans (Simplified). Script can combine with region — zh-Hans-US is valid.
- Common errors:
eng (ISO 639-2, invalid) instead of en; jp instead of ja; bare zh is valid but ambiguous for script-specific pages — prefer zh-Hans/zh-Hant.
5. Region code validation
- Optional region qualifier uses ISO 3166-1 Alpha-2 (
en-US, en-GB, pt-BR), format language-REGION (lowercase-UPPERCASE).
- A country code alone is invalid — no region without a language. Google's own bad example,
be, is actually the Belarusian language code, not Belgium.
- Common errors:
en-uk instead of en-GB (UK isn't a valid ISO 3166-1 region); EU/UN as a region (not valid values); es-LA (Latin America isn't a country — use specific countries); region without a language prefix.
5b. Geo-targeting signal hierarchy
Practical locale-signal heuristic (not a confirmed ranking order): ccTLD > hreflang annotations > server location/IP > addresses/language/currency/Business Profile. hreflang is a hint, not a directive. Google ignores locational meta tags and HTML geotargeting attributes. Search Console's International Targeting report and manual country-targeting setting were removed in 2022 — don't recommend GSC country targeting; hreflang is the remaining lever.
6. Canonical URL alignment
Hreflang tags must only appear on canonical URLs. If a page's rel=canonical points elsewhere, hreflang on that page is ignored. The canonical and hreflang URLs must match exactly, including trailing slashes.
7. Protocol consistency
All URLs in a hreflang set must use the same protocol. Mixed HTTP/HTTPS breaks validation — after an HTTPS migration, update every hreflang tag.
8. Cross-domain support
Hreflang works across domains (example.com + example.de) provided return tags exist on both sides. Sitemap-based implementation is recommended for cross-domain setups; use GSC verification or cross-site sitemap submission for monitoring.
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 at scale) |
| Language without region when needed | Low | Add region qualifier for geo-targeted content |
Implementation methods
| Method | Best for | Pros | Cons |
|---|
HTML <link> tags | <50 variants per page | Easy, visible in source | Bloats <head>, hard to maintain at scale |
| HTTP headers | Non-HTML files (PDFs, docs) | Works where there's no <head> | Complex server config, invisible in HTML |
| XML sitemap | Large sites, cross-domain, 50+ pages | Scalable, centralized | Not visible on-page, needs sitemap upkeep |
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" />
HTTP header:
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"
XML sitemap (see below for the full rules): use the xhtml:link entries inside each <url>.
Hreflang generation process
- Detect languages — scan for URL path, subdomain, TLD, and
<html lang> signals.
- Map page equivalents — match corresponding pages across languages/regions.
- Validate codes — check every code against ISO 639-1 and ISO 3166-1.
- Generate tags — for each page, including the self-reference.
- Verify return tags — confirm every relationship is bidirectional.
- Add x-default — set the fallback for each page set.
- Output — HTML, HTTP header, or sitemap XML per the chosen method.
Hreflang sitemap generation
<?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" = = />
Rules: include the xmlns:xhtml namespace; every <url> entry carries ALL alternates including itself; each alternate is a separate <url> entry with its own full set; split at whichever comes first — 50,000 URLs or 50MB uncompressed per sitemap file.
Cultural adaptation assessment
Beyond technical validation, assess whether content is culturally adapted per target market. Load references/cultural-profiles.md for pre-built profiles (DACH, Francophone, Hispanic, Japanese, plus a Default Profile checklist for unlisted locales).
Steps: identify all language versions and target markets → load the relevant 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 consistency → flag adaptation gaps as Medium severity. Output a Cultural Adaptation Score (0–100) per language version with specific findings.
Content parity audit
Load references/content-parity.md for the full parity matrix and scoring methodology.
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 run 25–35% longer than EN, JA 10–25% shorter); freshness tracking via timestamps; cultural-marker scanning (foreign brands, wrong legal references, untranslated elements). Output: a 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 tables per locale.
Checks: number-format consistency (e.g. 1,000.00 should read 1.000,00 on de-DE pages); date format matches locale expectations; currency symbols and placement correct for the target market; phone numbers in international format with the right country code.
Machine-translation QA flag
Load references/machine-translation-qa.md before flagging any translated page. Google's Quality Rater Guidelines treat unreviewed machine translation as scaled content abuse (§4.6.5) — the enforceable spam policy names "translating" among the automated transformations it targets. MT is fine when a human speaker reviewed and corrected it; untranslated or lightly post-edited MT (hallucinated terms, wrong agreement, untranslated proper nouns) is not. Surface signals like identical-except-chrome alternates, lang mismatching body content, and untrimmed auto-translated meta descriptions — see the reference for the full signal table and what NOT to flag (honestly-labelled MT fallback pages, i18n UI strings).
Validation report format
Hreflang validation report
Summary: pages scanned, language variants detected, issues found (Critical/High/Medium/Low).
| Language | URL | Self-Ref | Return Tags | x-default | Status |
|---|
| en-US | https://... | done | done | done | pass |
| fr | https://... | missing | partial | done | fail |
| de | https://... | done | missing | done | fail |
Plus: generated hreflang tags (HTML/header/sitemap, per chosen method) and recommendations (missing implementations, code fixes, method-migration suggestions).
Written to plans/marketing/<campaign>/seo-hreflang.md.
Key concepts
- Hint, not directive — hreflang tells Google your intent; it does not override ccTLD, server location, or content signals. A broken set is simply ignored, not penalized.
- Full mesh — every language version in a set must reference every other version, including itself. One missing edge breaks the whole set for everyone in it.
- Word expansion/contraction — Germanic/Romance languages run longer than English, CJK languages run shorter; content parity checks must expect this, not flag it as a gap.
Output
plans/marketing/<campaign>/seo-hreflang.md — validation report, generated tags, parity/cultural findings.- Inline recommendations in the conversation.
Cross-references
plans/marketing-context.md — required hub- [[seo]] — orchestrator; routes multi-region/multi-language sites here
- [[seo-technical]] — broader technical SEO (crawl, CWV, architecture)
- [[seo-local]] — local/regional business targeting (GBP, NAP, local pack)
- [[seo-content]] — writes the localized content this skill validates
.claude/workflows/marketing-rules.md — content quality rules
Provenance
Imported from AgriciDaniel/claude-seo and adapted for KitForge. Validation checks, implementation methods, cultural-profile/content-parity/locale-format/machine-translation-QA references preserved from source; output path retargeted to plans/marketing/<campaign>/.
