Source profileQuality 90/100

AgriciDaniel/claude-seo/skills/seo-hreflang/SKILL.md

seo-hreflang

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".

Source repository stars
13,280
Declared platforms
0
Static risk flags
1
Last source update
2026-07-27
Source checked
2026-08-04
DecisionCompatibilityInstallWorkflowPermissionsEvidenceSource

Decision brief

What it does—and where it fits

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

Best for

  • Use when user says "hreflang", "i18n SEO", "international SEO", "multi-language", "multi-region", or "language tags".

Not for

  • Tasks that require unconfirmed production actions or broad system permissions.
  • Environments where the pinned source and install steps cannot be inspected.

Compatibility matrix

Platform support, with evidence labels

PlatformStatusEvidenceWhat to check
CodexNot declaredNo explicit evidencePortability before use
Claude CodeNot declaredNo explicit evidencePortability before use
CursorNot declaredNo explicit evidencePortability before use
Gemini CLINot declaredNo explicit evidencePortability before use
Open the compatibility checker

Installation

Inspect first. Install second.

The source command is displayed only when detected. A safe inspection prompt is always available so your agent can explain every action before execution.

Source-detected install commandSource
npx skills add https://github.com/AgriciDaniel/claude-seo --skill "skills/seo-hreflang"
Safe inspection promptEditorial

Inspect the Agent Skill "seo-hreflang" from https://github.com/AgriciDaniel/claude-seo/blob/09d37c7b66ed3ca9c6efbdb765a805a6c76a8f01/skills/seo-hreflang/SKILL.md at commit 09d37c7b66ed3ca9c6efbdb765a805a6c76a8f01. List every install step, command, network request, credential, file read/write, external action, and rollback step. Explain whether it fits my task. Do not install or execute anything until I approve.

Workflow

What the source asks the agent to do

  1. 01

    Implementation Methods

    Best for: Sites with <50 language/region variants per page.

    Best for: Sites with <50 language/region variants per page.Place in section. Every page must include all alternates including itself.Best for: Non-HTML files (PDFs, documents).
  2. 02

    Process

    1. Detect languages: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute) 2. Map page equivalents: Match corresponding pages across languages/regions 3. Validate language codes: Verify all codes against ISO 639-1 and ISO 3166-1 4. Generate tags: Crea…

    Detect languages: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)Map page equivalents: Match corresponding pages across languages/regionsValidate language codes: Verify all codes against ISO 639-1 and ISO 3166-1
  3. 03

    Cultural Adaptation Assessment

    When analyzing a multi-language site, go beyond technical hreflang validation to assess whether the content is culturally adapted for each target market.

    Identify all language versions and their target marketsLoad the relevant cultural profile(s)Check CTAs match cultural expectations (direct vs indirect)
  4. 04

    Validation Checks

    Every page must include an hreflang tag pointing to itself

    Every page must include an hreflang tag pointing to itselfThe self-referencing URL must exactly match the page's canonical URLMissing self-referencing tags cause Google to ignore the entire hreflang set
  5. 05

    1. Self-Referencing Tags

    Every page must include an hreflang tag pointing to itself

    Every page must include an hreflang tag pointing to itselfThe self-referencing URL must exactly match the page's canonical URLMissing self-referencing tags cause Google to ignore the entire hreflang set

Permission review

Static risk signals and limitations

Network access

medium · line 97

The documentation includes network, browsing, or remote request actions.

<link rel="alternate" hreflang="en-US" href="https://example.com/page" />

Network access

medium · line 98

The documentation includes network, browsing, or remote request actions.

<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page" />

Evidence record

Why each signal appears

EvidenceSourceComputedTestedEditorial
SignalValueEvidence typeMeaning
Quality score90/100ComputedDocumentation, specificity, maintenance, and trust rules
Repository stars13,280SourceRepository attention, not individual Skill quality
Compatibility0 platformsSourceDeclared in the catalog source record
Usage guideautomated source guideEditorialGenerated or reviewed according to the visible evidence level

Pinned source

Provenance and original SKILL.md

Repository
AgriciDaniel/claude-seo
Skill path
skills/seo-hreflang/SKILL.md
Commit
09d37c7b66ed3ca9c6efbdb765a805a6c76a8f01
License
MIT
Collected
2026-08-04
Default branch
main
View the original SKILL.md

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

5. Region Code Validation

  • Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g., en-US, en-GB, pt-BR)
  • Format: language-REGION (lowercase language, uppercase region)
  • A country code alone is invalid, you cannot specify a region without a language (Google's own bad example is be, which is actually the Belarusian language code, not Belgium).
  • Common errors:
    • en-uk instead of en-GB (UK is not a valid ISO 3166-1 region code)
    • EU / UN as a region (not valid ISO 3166-1 values)
    • es-LA (Latin America is not a country; use specific countries)
    • Region without language prefix

5b. Geo-targeting signal hierarchy

  • Practical locale-signal heuristic: ccTLD > hreflang annotations > server location/IP > addresses/language/currency/Business Profile. Do not present this as a confirmed Google ranking order. hreflang is a hint, not a directive. Google ignores locational meta tags and HTML geotargeting attributes.
  • The Search Console International Targeting report and the manual country-targeting setting were removed in 2022, do not recommend setting country targeting in GSC; hreflang is the remaining lever.

6. Canonical URL Alignment

  • Hreflang tags must only appear on canonical URLs
  • If a page has rel=canonical pointing elsewhere, hreflang on that page is ignored
  • The canonical URL and hreflang URL must match exactly (including trailing slashes)
  • Non-canonical pages should not be in any hreflang set

7. Protocol Consistency

  • All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)
  • Mixed HTTP/HTTPS in hreflang sets causes validation failures
  • After HTTPS migration, update all hreflang tags to HTTPS

8. Cross-Domain Support

  • Hreflang works across different domains (e.g., example.com and example.de)
  • Cross-domain hreflang requires return tags on both domains
  • Use Google Search Console verification for monitoring or cross-site sitemap submission when needed
  • Sitemap-based implementation recommended for cross-domain setups

Common Mistakes

IssueSeverityFix
Missing self-referencing tagCriticalAdd hreflang pointing to same page URL
Missing return tags (A→B but no B→A)CriticalAdd matching return tags on all alternates
Missing x-default when fallback behavior is requiredMediumAdd x-default pointing to fallback/selector page
Invalid language code (e.g., eng)HighUse ISO 639-1 two-letter codes
Invalid region code (e.g., en-uk)HighUse ISO 3166-1 Alpha-2 codes
Hreflang on non-canonical URLHighMove hreflang to canonical URL only
HTTP/HTTPS mismatch in URLsMediumStandardize all URLs to HTTPS
Trailing slash inconsistencyMediumMatch canonical URL format exactly
Hreflang in both HTML and sitemapLowChoose one method (sitemap preferred for large sites)
Language without region when neededLowAdd region qualifier for geo-targeted content

Implementation Methods

Method 1: HTML Link Tags

Best for: Sites with <50 language/region variants per page.

<link rel="alternate" hreflang="en-US" href="https://example.com/page" />
<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />

Place in <head> section. Every page must include all alternates including itself.

Method 2: HTTP Headers

Best for: Non-HTML files (PDFs, documents).

Link: <https://example.com/page>; rel="alternate"; hreflang="en-US",
      <https://example.com/fr/page>; rel="alternate"; hreflang="fr",
      <https://example.com/page>; rel="alternate"; hreflang="x-default"

Set via server configuration or CDN rules.

Method 3: XML Sitemap (Recommended for large sites)

Best for: Sites with many language variants, cross-domain setups, or 50+ pages.

See Hreflang Sitemap Generation section below.

Method Comparison

MethodBest ForProsCons
HTML link tagsSmall sites (<50 variants)Easy to implement, visible in sourceBloats <head>, hard to maintain at scale
HTTP headersNon-HTML filesWorks for PDFs, imagesComplex server config, not visible in HTML
XML sitemapLarge sites, cross-domainScalable, centralized managementNot visible on page, requires sitemap maintenance

Hreflang Generation

Process

  1. Detect languages: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
  2. Map page equivalents: Match corresponding pages across languages/regions
  3. Validate language codes: Verify all codes against ISO 639-1 and ISO 3166-1
  4. Generate tags: Create hreflang tags for each page including self-referencing
  5. Verify return tags: Confirm all relationships are bidirectional
  6. Add x-default: Set fallback for each page set
  7. Output: Generate implementation code (HTML, HTTP headers, or sitemap XML)

Hreflang Sitemap Generation

Sitemap with Hreflang

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/page</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
    <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
  </url>
  <url>
    <loc>https://example.com/fr/page</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
    <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
  </url>
</urlset>

Key rules:

  • Include the xmlns:xhtml namespace declaration
  • Every <url> entry must include ALL language alternates (including itself)
  • Each alternate must appear as a separate <url> entry with its own full set
  • Split at whichever comes first: 50,000 URLs or 50MB uncompressed per sitemap file

Output

Hreflang Validation Report

Summary

  • Total pages scanned: XX
  • Language variants detected: XX
  • Issues found: XX (Critical: X, High: X, Medium: X, Low: X)

Validation Results

LanguageURLSelf-RefReturn Tagsx-defaultStatus
en-UShttps://...✅✅✅✅
frhttps://...❌⚠️✅❌
dehttps://...✅❌✅❌

Generated Hreflang Tags

  • HTML <link> tags (if HTML method chosen)
  • HTTP header values (if header method chosen)
  • hreflang-sitemap.xml (if sitemap method chosen)

Recommendations

  • Missing implementations to add
  • Incorrect codes to fix
  • Method migration suggestions (e.g., HTML to sitemap for scale)

Cultural Adaptation Assessment

When analyzing a multi-language site, go beyond technical hreflang validation to assess whether the content is culturally adapted for each target market.

Load references/cultural-profiles.md for pre-built profiles (DACH, Francophone, Hispanic, Japanese).

Assessment steps:

  1. Identify all language versions and their target markets
  2. Load the relevant cultural profile(s)
  3. Check CTAs match cultural expectations (direct vs indirect)
  4. Check trust signals are locale-appropriate (certifications, legal pages)
  5. Check for foreign brand references on localized pages
  6. Check number/date/currency formatting consistency
  7. Flag cultural adaptation issues as Medium severity

Output: Cultural Adaptation Score per language version (0-100) with specific findings.

Content Parity Audit

Command: /seo hreflang audit <directory-or-url>

Audit content parity across all language versions of a site or local content directory.

Load references/content-parity.md for the full parity matrix and scoring methodology.

What it checks:

  • Page existence across all declared languages
  • Section structure equivalence (H2/H3 count)
  • SEO element parity (title, meta, schema localization)
  • Word count ratio validation (DE should be 25-35% longer than EN, JA 10-25% shorter)
  • Freshness tracking (stale translations detected via timestamps)
  • Cultural marker scanning (foreign brands, wrong legal references, untranslated elements)

Output: Parity matrix table with per-page scores and prioritized action items.

Locale Format Validation

Load references/locale-formats.md for number, date, currency, address, and phone format reference tables per locale.

Checks:

  • Number format consistency (e.g., "1,000.00" should be "1.000,00" on de-DE pages)
  • Date format matches locale expectations
  • Currency symbols and placement correct for target market
  • Phone numbers use international format with correct country code

Reference Files

Load on-demand as needed (do NOT load all at startup):

  • references/cultural-profiles.md: DACH, Francophone, Hispanic, Japanese cultural adaptation profiles
  • references/locale-formats.md: Number, date, currency, address, phone format tables per locale
  • references/content-parity.md: Content parity audit methodology and scoring

Error Handling

ScenarioAction
URL unreachable (DNS failure, connection refused)Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again.
No hreflang tags foundReport the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method.
Invalid language/region codes detectedList each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement.
Cultural profile not available for languageUse the Default Profile checklist from cultural-profiles.md. Note that assessment is based on general guidelines, not a pre-built profile.
Content parity directory emptyReport that no content files were found. Suggest verifying the directory path or providing a URL for live site analysis.

Alternatives

Compare before choosing

Computed 83546

AgriciDaniel/codex-seo

seo-hreflang

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".

2026-07-200 platforms
Computed 9313,280

AgriciDaniel/claude-seo

seo-ecommerce

E-commerce SEO analysis: Google Shopping visibility, Amazon marketplace intelligence, product schema validation, competitor pricing analysis, and marketplace keyword gaps. Combines on-page product SEO with marketplace data from DataForSEO Merchant API. Use when user says "ecommerce SEO", "product SEO", "Google Shopping", "marketplace SEO", "product schema", "Amazon SEO", "product listings", "shopping ads", or "merchant SEO".

2026-07-270 platforms
Computed 9328

MoizIbnYousaf/marketing-cli

off-page-seo

Backlink + distribution checklist that expands a site's KD ceiling beyond what on-page work alone can earn. Use when the user mentions 'backlinks', 'off-page SEO', 'directory submissions', 'guest posts', 'outreach targets', 'link building', 'submit to directories', 'get listed in listicles', 'Product Hunt launch backlinks', or asks 'how do I get more domain authority'. Generates a prioritized, researched target list across directories, listicles, and guest-post candidates — does NOT submit anyth

2026-08-020 platforms
Computed 9237,425

github/awesome-copilot

competitor-ad-intelligence

Use this skill when the user asks to analyze, tear down, or reverse-engineer a competitor's paid ads. Trigger for prompts like "what ads is [competitor] running", "tear down their ad strategy", "competitor ad analysis", "find ad angles we haven't tried", or "reverse-engineer their paid funnel". Do not trigger for organic/SEO competitor research or website positioning analysis.

2026-08-040 platforms