seo-hreflang

Hreflang 与国际 SEO

共享数据缓存

步骤 0 —— 检查共享数据缓存：

开始收集信息前，检查 .seo-cache/，查找相关 SEO 技能中可复用的上下文。 参考：../seo/references/shared-data-cache.md，了解架构和依赖关系图。

如果存在，请检查以下缓存文件：

• .seo-cache/site-meta.json：查看域名、业务类型、行业和抓取上下文

• .seo-cache/audit-scores.json：查看之前完整审计的优先事项

• .seo-cache/pages/{url-slug}/page-analysis.json：提供 URL 时，查看页面级上下文

• 如果找到：解析并使用明确有效的字段（注明“正在使用缓存的 [X]（日期：[date]）”）

• 如果缺失、损坏或不相关：继续收集新证据

• 如果用户说“refresh”或“re-run”：忽略缓存读取，并在写入时覆盖

验证现有的 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）
• 常见错误：
  • 用 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）
• 格式：语言-地区（语言小写，地区大写）
• 常见错误：
  • 用 en-uk 代替 en-GB（UK 不是有效的 ISO 3166-1 代码）
  • 使用 es-LA（拉丁美洲不是一个国家；请使用具体国家）
  • 地区代码前缺少语言前缀

6. 规范 URL 对齐

• hreflang 标签只能出现在规范 URL 上
• 如果页面的 rel=canonical 指向其他位置，该页面上的 hreflang 将被忽略
• 规范 URL 与 hreflang URL 必须完全一致（包括尾部斜杠）
• 非规范页面不应出现在任何 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 代码
hreflang 指向非规范 URL	高	仅将 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 站点地图	大型网站、跨域网站	可扩展、集中管理	页面上不可见，需要维护站点地图

Hreflang 生成

流程

1. 检测语言：扫描网站中的语言标识（URL 路径、子域名、顶级域名、HTML lang 属性）
2. 映射对应页面：匹配不同语言／地区的对应页面
3. 验证语言代码：根据 ISO 639-1 和 ISO 3166-1 验证所有代码
4. 生成标签：为每个页面创建 hreflang 标签，包括自引用标签
5. 验证返回标签：确认所有关系均为双向
6. 添加 x-default：为每组页面设置备用版本
7. 输出：生成实现代码（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 迁移到站点地图）

文化适配评估

分析多语言网站时，除了验证技术层面的 hreflang，还要评估内容是否针对每个目标市场进行了文化适配。

加载 references/cultural-profiles.md 获取预置的文化档案（DACH、法语区、西语区、日本）。

评估步骤：

1. 找出所有语言版本及其目标市场
2. 加载相关文化档案
3. 检查 CTA 是否符合文化习惯（直接或间接）
4. 检查信任信号是否符合当地要求（认证、法律页面）
5. 检查本地化页面上是否提及外国品牌
6. 检查数字、日期和货币格式是否一致
7. 将文化适配问题标记为中等严重程度

**输出：**每个语言版本的文化适配得分（0-100）及具体发现。

内容一致性审计

命令：/seo hreflang audit <directory-or-url>

审计网站或本地内容目录中所有语言版本的内容一致性。

加载 references/content-parity.md 获取完整的一致性矩阵和评分方法。

检查内容：

• 所有已声明语言版本中的页面是否存在
• 章节结构是否等效（H2/H3 数量）
• SEO 元素是否一致（标题、元数据、本地化的 schema）
• 字数比例验证（DE 应比 EN 长 25-35%，JA 应比 EN 短 10-25%）
• 内容新鲜度跟踪（通过时间戳检测过时翻译）
• 文化标记扫描（外国品牌、错误的法律引用、未翻译内容）

**输出：**包含各页面得分和按优先级排列的待办事项的矩阵表。

区域格式验证

加载 references/locale-formats.md，查看各区域的数字、日期、货币、地址和电话号码格式参考表。

检查内容：

• 数字格式一致性（例如，de-DE 页面上的 "1,000.00" 应为 "1.000,00"）
• 日期格式是否符合区域习惯
• 货币符号及其位置是否符合目标市场习惯
• 电话号码是否采用带正确国家代码的国际格式

参考文件

按需加载（启动时不要全部加载）：

• references/cultural-profiles.md：DACH、法语区、西语区、日本的文化适配档案
• references/locale-formats.md：各区域的数字、日期、货币、地址和电话号码格式表
• references/content-parity.md：内容一致性审计方法和评分

错误处理

情况	操作
URL 无法访问（DNS 故障、连接被拒绝）	清楚说明错误。不要猜测网站结构。建议用户检查 URL 后重试。
未找到 hreflang 标签	报告缺失情况。检查其他国际化信号（子目录、子域名、ccTLD），并建议合适的 hreflang 实现方式。
检测到无效的语言/区域代码	列出每个无效代码及其正确替代项。提供可直接实施的修正后 hreflang 标签集。
语言没有可用的文化档案	使用 cultural-profiles.md 中的 Default Profile 检查清单。说明评估依据为通用指南，而非预置档案。
内容一致性目录为空	报告未找到内容文件。建议检查目录路径，或提供 URL 以分析线上网站。

写入共享数据缓存

完成所有工作后，如果工作流产生了可长期保留的发现，则将简洁的 JSON 摘要写入 .seo-cache/。 使用 ../seo/references/shared-data-cache.md 中的 schema 和命名规则；至少包含 cache_type、analyzed_at、源 URL/域名、关键发现、问题、建议和工具限制。如果 .gitignore 中缺少 .seo-cache/，则将其添加进去。