hreflang-check

/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

1. 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.
2. 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.
3. 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.
4. 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.
   • (c) Valid language-region codes: Validate every hreflang value against ISO 639-1 for the language component and ISO 3166-1 Alpha-2 for the optional region component. Common errors: using en-UK instead of en-GB, using three-letter codes like eng instead of en, using country codes alone like US without the language prefix. Severity: critical for invalid codes (search engines ignore them), warning for non-standard but parseable codes.
   • (d) x-default tag present: Check that an x-default hreflang annotation exists, pointing to the fallback page for users whose language does not match any specific hreflang. Typically points to the English version or a language selector page. Missing x-default means users in non-targeted regions may see an arbitrary language version. Severity: warning.
   • (e) No duplicate language codes: Check that each page does not have multiple hreflang annotations with the same language-region code pointing to different URLs. Duplicate codes create ambiguity and search engines may ignore all annotations for that language. Severity: critical.
   • (f) URLs are absolute: Verify all href values in hreflang annotations are absolute URLs (starting with https:// or http://), not relative paths. Relative URLs in hreflang are invalid per the specification. Severity: critical.
   • (g) URL consistency: Check that all referenced URLs use consistent protocols (all HTTPS or all HTTP, not mixed), consistent www/non-www prefixes, and consistent trailing slash conventions. Inconsistencies may cause search engines to treat references as pointing to different pages. Severity: warning.
5. Cross-reference against brand language configuration: Compare the set of language-region codes found in hreflang annotations against the brand's configured languages (from profile.json language config or user-provided expected codes). Flag any configured language that is missing from hreflang annotations — this means a language the brand actively targets has no hreflang support, so search engines cannot properly route users to that language version. Also flag any hreflang language codes that are not in the brand's configuration — these may be legitimate (languages configured elsewhere) or may indicate stale annotations for discontinued language versions.
6. Generate prioritized fix list with code snippets: For every issue found, generate the specific corrected hreflang code. For missing self-referential tags: provide the exact <link rel="alternate" hreflang="xx-XX" href="https://..."> tag to add. For bidirectional mismatches: provide the tags that need to be added to the page missing the back-reference. For invalid codes: provide the corrected code with the valid language-region value. For missing x-default: provide the recommended x-default tag with the appropriate fallback URL. Group fixes by page so implementation can be done page-by-page, and also group by issue type so systemic problems (e.g., "self-referential tags missing on all 47 blog posts") can be addressed with a single template fix rather than 47 individual corrections.

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