Hreflang 标签生成与验证工具 - 多语言网站SEO优化，支持HTML、HTTP头部、XML站点地图

seo-hreflang by agricidaniel/claude-seo

388 周安装量

3,000 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/agricidaniel/claude-seo --skill seo-hreflang

开发自动化 SEO

🇨🇳中文介绍

Hreflang 与国际化 SEO

验证现有的 hreflang 实现，或为多语言和多区域网站生成正确的 hreflang 标签。支持 HTML、HTTP 头部和 XML 站点地图实现。

验证检查

1. 自引用标签

每个页面必须包含一个指向自身的 hreflang 标签
自引用 URL 必须与页面的规范 URL 完全匹配
缺少自引用标签会导致 Google 忽略整个 hreflang 集合

2. 返回标签

如果页面 A 使用 hreflang 链接到页面 B，则页面 B 必须链接回页面 A
每个 hreflang 关系必须是双向的（A→B 和 B→A）
缺少返回标签会使两个页面的 hreflang 信号失效
检查所有语言版本是否相互引用（完全网状结构）

3. x-default 标签

必需：指定未匹配语言/区域的回退页面
通常指向语言选择器页面或英语版本
每组替代页面中只能有一个 x-default
也必须包含来自所有其他语言版本的返回标签

4. 语言代码验证

必须使用 ISO 639-1 双字母代码（例如 en、fr、de、ja）
常见错误：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

5. 区域代码验证

可选的区域限定符使用 ISO 3166-1 Alpha-2（例如 en-US、en-GB、pt-BR）
格式：语言-区域（语言小写，区域大写）
常见错误：
- 使用 en-uk 而非 en-GB（UK 不是有效的 ISO 3166-1 代码）
- 使用 es-LA（拉丁美洲不是国家 — 使用特定国家）
- 区域代码没有语言前缀

6. 规范 URL 对齐

Hreflang 标签只能出现在规范 URL 上
如果一个页面的 rel=canonical 指向其他地方，则该页面上的 hreflang 将被忽略
规范 URL 和 hreflang URL 必须完全匹配（包括尾部斜杠）
非规范页面不应出现在任何 hreflang 集合中

hreflang 集合中的所有 URL 必须使用相同的协议（HTTPS 或 HTTP）
hreflang 集合中混合 HTTP/HTTPS 会导致验证失败
HTTPS 迁移后，将所有 hreflang 标签更新为 HTTPS

Hreflang 适用于不同的域（例如 example.com 和 example.de）
跨域 hreflang 要求两个域上都有返回标签
验证两个域是否都在 Google Search Console 中验证过
对于跨域设置，建议使用基于站点地图的实现

问题	严重性	修复方法
缺少自引用标签	严重	添加指向同一页面 URL 的 hreflang
缺少返回标签（A→B 但没有 B→A）	严重	在所有替代页面上添加匹配的返回标签
缺少 x-default	高	添加指向回退/选择器页面的 x-default
无效的语言代码（例如 `eng`）	高	使用 ISO 639-1 双字母代码
无效的区域代码（例如 `en-uk`）	高	使用 ISO 3166-1 Alpha-2 代码
在非规范 URL 上使用 hreflang	高	仅将 hreflang 移至规范 URL
URL 中 HTTP/HTTPS 不匹配	中	将所有 URL 标准化为 HTTPS
尾部斜杠不一致	中	完全匹配规范 URL 格式
同时在 HTML 和站点地图中使用 hreflang	低	选择一种方法 — 大型站点首选站点地图
需要时语言代码缺少区域限定符	低	为地理定位内容添加区域限定符

方法 1：HTML 链接标签

最适合：每个页面语言/区域变体少于 50 个的网站。

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

放置在 <head> 部分。每个页面必须包含所有替代页面，包括其自身。

方法 2：HTTP 头部

最适合：非 HTML 文件（PDF、文档）。

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"

通过服务器配置或 CDN 规则设置。

方法 3：XML 站点地图（大型站点推荐）

最适合：具有许多语言变体、跨域设置或 50 个以上页面的网站。

请参阅下面的 Hreflang 站点地图生成部分。

方法	最适合	优点	缺点
HTML 链接标签	小型站点（<50 个变体）	易于实现，在源代码中可见	使 `<head>` 臃肿，大规模维护困难
HTTP 头部	非 HTML 文件	适用于 PDF、图片	服务器配置复杂，在 HTML 中不可见
XML 站点地图	大型站点、跨域	可扩展、集中管理	在页面上不可见，需要维护站点地图

检测语言：扫描网站以查找语言指示符（URL 路径、子域名、顶级域名、HTML lang 属性）
映射页面等价物：匹配跨语言/区域的对应页面
验证语言代码：根据 ISO 639-1 和 ISO 3166-1 验证所有代码
生成标签：为每个页面创建 hreflang 标签，包括自引用
验证返回标签：确认所有关系都是双向的
添加 x-default：为每个页面集合设置回退
输出：生成实现代码（HTML、HTTP 头部或站点地图 XML）

Hreflang 站点地图生成

带 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>

包含 xmlns:xhtml 命名空间声明
每个 <url> 条目必须包含所有语言替代页面（包括其自身）
每个替代页面必须作为单独的 <url> 条目出现，并包含其自己的完整集合
每个站点地图文件最多包含 50,000 个 URL

Hreflang 验证报告

扫描的总页面数：XX
检测到的语言变体数：XX
发现的问题数：XX（严重：X，高：X，中：X，低：X）

语言	URL	自引用	返回标签	x-default	状态
en-US	https://...	✅	✅	✅	✅
fr	https://...	❌	⚠️	✅	❌
de	https://...	✅	❌	✅	❌

生成的 Hreflang 标签

HTML <link> 标签（如果选择了 HTML 方法）
HTTP 头部值（如果选择了头部方法）
hreflang-sitemap.xml（如果选择了站点地图方法）

需要添加的缺失实现
需要修复的错误代码
方法迁移建议（例如，为扩展性从 HTML 迁移到站点地图）

🇺🇸English

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

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

Detect languages : Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
Map page equivalents : Match corresponding pages across languages/regions
Validate language codes : Verify all codes against ISO 639-1 and ISO 3166-1
Generate tags : Create hreflang tags for each page including self-referencing
Verify return tags : Confirm all relationships are bidirectional
Add x-default : Set fallback for each page set
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 → sitemap for scale)

Weekly Installs

152

Repository

agricidaniel/claude-seo

GitHub Stars

2.1K

First Seen

Feb 10, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode139

codex137

gemini-cli134

github-copilot133

cursor131

claude-code130

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

138,300 周安装