# SEO Hreflang

Hreflang and international SEO audit, validation, and generation.

- Repository: https://github.com/AgriciDaniel/claude-seo (25484 stars)
- Category: Marketing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AgriciDaniel/claude-seo --skill seo-hreflang -g -a claude-code -y`
Codex: `npx skills add AgriciDaniel/claude-seo --skill seo-hreflang -g -a codex -y`
Cursor: `npx skills add AgriciDaniel/claude-seo --skill seo-hreflang -g -a cursor -y`
Gemini CLI: `npx skills add AgriciDaniel/claude-seo --skill seo-hreflang -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add AgriciDaniel/claude-seo`

## Description

Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang implementations. Use when user says "hreflang", "i18n SEO", "international SEO", "multi-language", "multi-region", or "language tags".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Hreflang & International SEO

Validate existing hreflang implementations or generate correct hreflang tags
for multi-language and multi-region sites. Supports HTML, HTTP header, and
XML sitemap implementations.

## Validation Checks

### 1. Self-Referencing Tags
- Every page must include an hreflang tag pointing to itself
- The self-referencing URL must exactly match the page's canonical URL
- Missing self-referencing tags cause Google to ignore the entire hreflang set

### 2. Return Tags
- If page A links to page B with hreflang, page B must link back to page A
- Every hreflang relationship must be bidirectional (A→B and B→A)
- Missing return tags invalidate the hreflang signal for both pages
- Check all language versions reference each other (full mesh)

### 3. x-default Tag
- Recommended when a selector/fallback URL exists: designates the fallback page for unmatched languages/regions
- Typically points to the language selector page or English version
- Only one x-default per set of alternates
- Must also have return tags from all other language versions

### 4. Language Code Validation
- Must use ISO 639-1 two-letter codes (e.g., `en`, `fr`, `de`, `ja`)
- An **optional ISO 15924 script subtag** is the documented, official mechanism
  for script: `zh-Hant` (Traditional) / `zh-Hans` (Simplified). Script may
  combine with a region, e.g. `zh-Hans-US` is valid (language + script + region).
- Common errors:
  - `eng` instead of `en` (ISO 639-2, not valid for hreflang)
  - `jp` instead of `ja` (incorrect code for Japanese)
  - `zh` is valid but ambiguous for script-specific pages; prefer `zh-Hans` or `zh-Hant` when targeting a script

The rest: https://github.com/AgriciDaniel/claude-seo/blob/HEAD/skills/seo-hreflang/SKILL.md