AGENT SKILL

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

适用职业市场营销
使用场景营销推广
License 许可
MIT
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
seo-hreflang
license
MIT
metadata
{ "author": "AgriciDaniel", "version": "1.7.0", "category": "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".
argument-hint
[url]
user-invokable
true

02 资源文件 1

03 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

  • Required: 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)
  • Common errors:
    • eng instead of en (ISO 639-2, not valid for hreflang)
    • jp instead of ja (incorrect code for Japanese)
    • zh without region qualifier (ambiguous; use zh-Hans or zh-Hant)

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)
  • Common errors:
    • en-uk instead of en-GB (UK is not a valid ISO 3166-1 code)
    • es-LA (Latin America is not a country; use specific countries)
    • Region without language prefix

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
  • Verify both domains are verified in Google Search Console
  • Sitemap-based implementation recommended for cross-domain setups

Common Mistakes

Issue Severity Fix
Missing self-referencing tag Critical Add hreflang pointing to same page URL
Missing return tags (A→B but no B→A) Critical Add matching return tags on all alternates
Missing x-default High Add x-default pointing to fallback/selector page
Invalid language code (e.g., eng) High Use ISO 639-1 two-letter codes
Invalid region code (e.g., en-uk) High Use ISO 3166-1 Alpha-2 codes
Hreflang on non-canonical URL High Move hreflang to canonical URL only
HTTP/HTTPS mismatch in URLs Medium Standardize all URLs to HTTPS
Trailing slash inconsistency Medium Match canonical URL format exactly
Hreflang in both HTML and sitemap Low Choose one method (sitemap preferred for large sites)
Language without region when needed Low Add 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

Method Best For Pros Cons
HTML link tags Small sites (<50 variants) Easy to implement, visible in source Bloats <head>, hard to maintain at scale
HTTP headers Non-HTML files Works for PDFs, images Complex server config, not visible in HTML
XML sitemap Large sites, cross-domain Scalable, centralized management Not 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 50,000 URLs 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

Language URL Self-Ref Return Tags x-default Status
en-US https://... ✅ ✅ ✅ ✅
fr https://... ❌ ⚠️ ✅ ❌
de https://... ✅ ❌ ✅ ❌

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)

Error Handling

Scenario Action
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 found Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method.
Invalid language/region codes detected List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement.

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k