/hreflang-check

name: hreflang-check
description: "Audit hreflang tags. Use when: checking missing tags, incorrect language codes, or x-default configuration."

/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 (se