# seo-hreflang

> Hreflang and international SEO audit, validation, and generation covering self-referencing tags, return tags, x-default placement, ISO language and region code validation, canonical alignment, and cultural adaptation assessment.

**Use case**: Fix international SEO before Google ignores your hreflang

**Canonical URL**: https://agentcookbooks.com/skills/seo-hreflang/

**Topics**: claude-code, skills, marketing, seo

**Trigger phrases**: "hreflang", "international SEO", "multi-language", "multi-region", "i18n SEO"

**Source**: [AgriciDaniel](https://github.com/AgriciDaniel/claude-seo/tree/main/skills/seo-hreflang)

**License**: MIT

---

## What it does

`seo-hreflang` is a Claude Code skill from AgriciDaniel's [claude-seo repo](https://github.com/AgriciDaniel/claude-seo). 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](https://github.com/AgriciDaniel/claude-seo/tree/main/skills/seo-hreflang) 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](https://github.com/AgriciDaniel). The canonical SKILL.md and supporting files live in the [`seo-hreflang` folder](https://github.com/AgriciDaniel/claude-seo/tree/main/skills/seo-hreflang) of the [claude-seo repository](https://github.com/AgriciDaniel/claude-seo).

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.