seo-hreflang

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• hreflang
• international SEO
• multi-language
• multi-region
• i18n SEO

What it does

seo-hreflang is a Claude Code skill from AgriciDaniel’s claude-seo repo. It validates existing hreflang implementations or generates correct hreflang tags for multi-language and multi-region sites, supporting all three implementation methods: HTML link tags, HTTP headers, and XML sitemap.

The validation runs eight checks in severity order: self-referencing tags (missing = Google ignores the entire hreflang set), return tags (every A→B relationship needs a B→A), x-default presence (required fallback, only one per alternate set), ISO 639-1 language codes (catches eng vs en, jp vs ja), ISO 3166-1 Alpha-2 region codes (catches en-uk vs en-GB), canonical URL alignment (hreflang only on canonical URLs), protocol consistency (no mixing HTTP/HTTPS), and cross-domain support requirements. Beyond technical validation the skill includes a Cultural Adaptation Assessment (pre-built profiles for DACH, Francophone, Hispanic, and Japanese markets) and a Content Parity Audit (checks whether all language versions have equivalent page coverage, section structure, SEO elements, and word count ratios).

When to use it

Reach for it when:

• You have a multi-language site and rankings in some locales are weaker than expected
• A CMS migration just touched URL structure and you need to verify all hreflang return tags are still intact
• You are building a new multi-region site and want to generate the correct implementation before launch

When not to reach for it:

• The site is single-language and single-region; hreflang has no relevance here
• You want content translated — this skill audits and generates technical tags, not content

Install

Copy the seo-hreflang SKILL.md into .claude/skills/seo-hreflang/.

Trigger phrases: “hreflang”, “i18n SEO”, “international SEO”, “multi-language”, “multi-region”, “language tags”.

Invoke with /seo hreflang <url> for validation, or provide a URL directory for content parity audit. For generation, describe the target language/region set and preferred implementation method (HTML, HTTP header, or XML sitemap).

What a session looks like

A typical session has three phases:

1. Technical validation. All eight checks run against the fetched page. Missing self-referencing tags and missing return tags are flagged as Critical — these are the most common causes of hreflang being silently ignored by Google. Each finding includes the correct replacement tag ready to implement.
2. Cultural adaptation assessment (if multi-language). The skill loads the relevant pre-built cultural profiles (DACH, Francophone, Hispanic, or Japanese) and checks CTAs for cultural appropriateness, trust signals for locale expectations, number/date/currency formatting, and untranslated elements or foreign brand references.
3. Output and recommendation. A validation report table shows status per language with per-check results. For generation, the output is either HTML link tags, HTTP header values, or a complete hreflang-sitemap.xml depending on the chosen implementation method — ready to paste or file.

Receipts

Works well: The most common failure mode this skill catches is the return tag problem — a site adds en-US → fr links but forgets the fr → en-US return links on the French pages. This silently invalidates both sides of the relationship, and it is invisible without a dedicated hreflang audit.

Backfires: The cultural adaptation assessment relies on pre-built profiles for four markets. For locales without a profile (e.g., Arabic, Thai, Korean), the skill falls back to generic guidelines and notes the limitation — which means the cultural audit is less useful for less-common market combinations.

Pattern that works: For large sites with 50+ pages across 3+ languages, the XML sitemap implementation method is strongly preferable to HTML link tags — it centralizes management and eliminates the risk of return tag gaps caused by template differences between language versions.

Source and attribution

Originally written by AgriciDaniel. The canonical SKILL.md and supporting files live in the seo-hreflang folder of the claude-seo repository.

License: MIT. Install, adapt, and redistribute with attribution preserved.

This page documents the skill from a practitioner’s perspective. For the formal spec and updates, defer to the source repo.