| name | 30x-seo-hreflang |
| description | Hreflang 和国际 SEO 审核、验证和生成。检测常见错误，验证语言/地区代码， 生成正确的 hreflang 实现。当用户说"hreflang"、"国际SEO"、"多语言"、 "多地区"或"语言标签"时使用。
|
| allowed-tools | ["WebFetch","Read"] |
Hreflang 与国际 SEO
验证现有 hreflang 实现或为多语言和多地区网站生成正确的 hreflang 标签。
支持 HTML、HTTP 响应头和 XML 站点地图实现。
验证检查
1. 自引用标签
- 每个页面必须包含指向自身的 hreflang 标签
- 自引用 URL 必须与页面的 canonical 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）
- 常见错误：
eng 而非 en（ISO 639-2，对 hreflang 无效）jp 而非 ja（日语的错误代码）zh 没有地区限定符（模糊 — 使用 zh-Hans 或 zh-Hant）
5. 地区代码验证
- 可选的地区限定符使用 ISO 3166-1 Alpha-2（如
en-US、en-GB、pt-BR）
- 格式：
language-REGION（小写语言，大写地区）
- 常见错误：
en-uk 而非 en-GB（UK 不是有效的 ISO 3166-1 代码）es-LA（拉丁美洲不是国家 — 使用具体国家）- 没有语言前缀的地区
6. Canonical URL 对齐
- Hreflang 标签只能出现在 canonical URL 上
- 如果页面有
rel=canonical 指向其他地方，该页面上的 hreflang 被忽略
- Canonical URL 和 hreflang URL 必须完全匹配（包括尾部斜杠）
- 非 canonical 页面不应出现在任何 hreflang 集中
7. 协议一致性
- hreflang 集中的所有 URL 必须使用相同协议（HTTPS 或 HTTP）
- hreflang 集中混合 HTTP/HTTPS 导致验证失败
- HTTPS 迁移后，更新所有 hreflang 标签为 HTTPS
8. 跨域支持
- 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 代码 |
| 非 canonical URL 上的 hreflang | 高 | 只在 canonical URL 上放置 hreflang |
| URL 中 HTTP/HTTPS 不匹配 | 中 | 统一所有 URL 为 HTTPS |
| 尾部斜杠不一致 | 中 | 精确匹配 canonical URL 格式 |
| HTML 和站点地图中都有 hreflang | 低 | 选择一种方法 — 大型网站推荐站点地图 |
| 需要时语言没有地区 | 低 | 为地理定向内容添加地区限定符 |
实现方法
方法 1：HTML Link 标签
最适合：每页语言/地区变体 <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 link 标签 | 小型网站（<50 变体） | 易于实现，源码可见 | <head> 膨胀，规模化难维护 |
| HTTP 响应头 | 非 HTML 文件 | 适用于 PDF、图片 | 服务器配置复杂，HTML 中不可见 |
| XML 站点地图 | 大型网站、跨域 | 可扩展，集中管理 | 页面上不可见，需要站点地图维护 |
Hreflang 生成
流程
- 检测语言：扫描网站的语言指示器（URL 路径、子域、TLD、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 → 站点地图以便扩展）
[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
