/dm: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 (/dm:brand-setup)?" — or proceed with defaults.