| name | hreflang-check |
| description | Audit hreflang implementation from supplied HTML, sitemap XML, or SEO-tool exports (it does not crawl sites) — running seven checks: self-referential tags, bidirectional pairs, valid ISO 639-1/3166-1 codes, x-default, duplicates, absolute URLs, and URL consistency — producing a 0-100 score, a language coverage matrix, and corrected code snippets per issue. Triggers on "/digital-marketing-pro:hreflang-check", "audit our hreflang tags", "why is Google serving the wrong language version", "check x-default configuration", "validate our international SEO tags". Compares findings against the brand's configured languages in profile.json to flag markets with no hreflang coverage. |
/digital-marketing-pro:hreflang-check
Purpose
Audit hreflang tag implementation for multilingual and multi-regional SEO. Hreflang annotations tell search engines which language and regional version of a page to serve to which audience — when implemented incorrectly, the wrong language version appears in search results, pages compete against each other for the same queries, and international organic traffic is lost to mis-served content. This command performs a thorough technical audit of hreflang implementation, checking that all language versions are properly cross-referenced with correct annotations, that every page references itself, that references are bidirectional (if page A points to page B, page B points back to page A), that language-region codes are valid, that x-default fallback is configured, and that no orphaned references point to non-existent pages.
Critical for any brand operating multilingual or multi-regional websites. Hreflang errors are among the most common international SEO issues — they are invisible to users, rarely caught in manual QA, and silently degrade search performance across every affected market. Even a single missing bidirectional reference can prevent search engines from correctly associating language versions, causing the wrong page to rank or duplicate content signals to suppress both versions. This command surfaces every implementation error with specific fix instructions and corrected code snippets.
Input Required
The user must provide (or will be prompted for):
- Website URL or sitemap URL: The starting point for the audit. Can be a single page URL (audits hreflang on that page and its referenced alternates), a sitemap URL (audits all pages listed in the sitemap), or a list of specific page URLs to check. Note: the plugin does not crawl websites directly — if a URL is provided, the user will be guided to provide the HTML source or hreflang data for analysis. Alternatively, the user can paste HTML source, hreflang tag sets, or exported hreflang data directly
- Specific page URLs to check (optional): A subset of pages to focus the audit on — useful for auditing a specific section (e.g., all product pages, all blog posts) rather than the entire site. If omitted, all pages with hreflang annotations in the provided data are audited
- Expected language-region codes (optional): The set of language-region codes that should appear in hreflang annotations (e.g., en-US, de-DE, fr-FR, es-ES, ja-JP). Defaults to the brand's configured languages from the language configuration in profile.json. Used to flag missing language versions — if the brand targets de-DE but no hreflang for de-DE exists on a page, that is flagged as a gap
Process
- Load brand context: Read
~/.claude-marketing/brands/_active-brand.json for the active slug, then load ~/.claude-marketing/brands/{slug}/profile.json. Load the language configuration to determine expected languages — primary language, secondary languages, and content languages. These form the expected hreflang set that every page should ideally reference. Apply compliance rules for target markets (skills/context-engine/compliance-rules.md) and industry context. Also check for guidelines at ~/.claude-marketing/brands/{slug}/guidelines/_manifest.json — if present, load any international SEO guidelines. Check for agency SOPs at ~/.claude-marketing/sops/. If no brand exists, ask: "Set up a brand first (/digital-marketing-pro:brand-setup)?" — or proceed with defaults.
- Obtain hreflang data: If a URL is provided, note that actual website crawling requires external tooling — the plugin does not perform HTTP requests to arbitrary websites. Guide the user to provide hreflang data in one of these formats: (a) raw HTML source of pages containing
<link rel="alternate" hreflang="..." href="..."> tags, (b) HTTP header hreflang annotations, (c) XML sitemap with xhtml:link hreflang entries, (d) a structured export from an SEO tool (Screaming Frog, Sitebulb, Ahrefs) listing hreflang annotations per URL, or (e) a manually compiled list of URL-to-language mappings. If the user has already provided HTML or hreflang data inline, proceed directly to parsing.
- Parse all hreflang annotations: Extract every hreflang annotation from the provided data. For each page, build a map of: the page's own URL, and every
hreflang attribute with its associated href URL. Track the source of each annotation (HTML <link> tag, HTTP header, or XML sitemap) since implementation method affects how fixes should be applied. Build a complete cross-reference matrix: for every page, which other pages does it reference, and in which languages.
- Check each page for hreflang correctness: For every page with hreflang annotations, run the following checks:
- (a) Self-referential tag present: Every page must include a hreflang annotation pointing to itself with its own language-region code. Missing self-referential tags are the most common hreflang error and cause search engines to ignore the entire hreflang set for that page. Severity: critical.
- (b) Bidirectional references: If page A in en-US references page B in de-DE, then page B must also reference page A in en-US. Check every reference pair for bidirectional consistency. One-directional references are treated as errors by search engines and may cause the entire annotation set to be disregarded. Severity: critical.
Output
A structured hreflang audit report containing:
- Hreflang audit score: Overall implementation quality score (0-100) reflecting the ratio of correct annotations to total annotations, weighted by issue severity — critical issues reduce the score significantly, warnings moderately, and info items minimally
- Audit summary statistics: Total pages audited, total hreflang annotations found, total unique language-region codes detected, total issues found (broken down by critical/warning/info), and percentage of pages with fully correct hreflang implementation
- Issues by type: Grouped findings for each check category — missing self-referential tags (count and affected pages), orphaned references (references pointing to non-existent or non-responding pages), invalid language-region codes (with the invalid code and correction), missing x-default (pages without fallback configuration), bidirectional mismatches (page pairs where the reference is one-directional), duplicate language codes (pages with conflicting annotations for the same language), relative URLs (annotations using non-absolute paths), and URL consistency issues (mixed protocols, www/non-www, trailing slash mismatches)
- Specific fix recommendations: For every issue, the exact corrected hreflang code snippet ready for implementation — the user can copy the corrected
<link> tag or sitemap entry directly into their page. Fixes are grouped both by page (for page-level implementation) and by issue type (for systemic fixes across the site)
- Language coverage matrix: A table showing pages (rows) versus language-region codes (columns), with each cell indicating whether a correct hreflang annotation exists (pass), exists with issues (warning), or is missing (gap). Immediately visualizes which pages have complete hreflang coverage and which have holes
- Brand language configuration comparison: Side-by-side comparison of the brand's configured languages versus the languages found in hreflang annotations — highlighting languages that the brand targets but that have no hreflang support (missing coverage), and hreflang languages that are not in the brand's configuration (potentially stale or unmanaged)
- Implementation method notes: Based on the source of annotations (HTML link tags, HTTP headers, XML sitemap), provide implementation-specific guidance for applying fixes — where to add tags in the HTML
<head>, how to configure HTTP headers, or how to update the XML sitemap with xhtml:link entries
Agents Used
- seo-specialist — Leads the hreflang technical audit. Parses hreflang annotations from HTML, HTTP headers, and XML sitemaps. Executes all seven validation checks (self-referential, bidirectional, valid codes, x-default, duplicate codes, absolute URLs, URL consistency) against international SEO specifications. Generates corrected hreflang code snippets for every issue found. Assesses the SEO impact of hreflang errors on international search visibility and provides prioritization guidance based on which fixes will have the greatest impact on organic traffic routing. References
skills/technical-seo/international-seo.md for hreflang specification details and best practices
- localization-specialist — Validates language-region codes against ISO 639-1 and ISO 3166-1 standards, cross-references hreflang language coverage against the brand's configured languages to identify coverage gaps, and flags language codes that may be technically valid but inappropriate for the brand's target markets (e.g., generic
zh instead of zh-Hans or zh-Hant for distinct Chinese market targeting). Provides language-specific context for the coverage matrix and recommends language-region granularity based on the brand's market strategy
