Claude SEO 项目 hreflang 技能实战指南：国际 SEO 审核、标签生成与多语言内容一致性审计

导读

本指南围绕 Claude SEO 项目（GitHub 加速计划 / cl / claude-seo）中的seo-hreflang子技能展开，系统讲解多语言、多地区网站的 hreflang 标签校验、生成与落地方法。你将掌握三类 hreflang 实现方式（HTML<link>、HTTP 头、XML Sitemap）的完整细节，学会用 8 项校验规则排查自引用缺失、返回标签不完整、x-default 遗漏、语言/地区代码错误等高频问题，并进一步运用文化适应评估、内容一致性审计（Content Parity Audit）与语言格式校验，把「技术层面正确的 hreflang」升级为「真正本地化的国际 SEO 方案」。技能本体位于 skills/seo-hreflang/SKILL.md，配套参考文件与项目源码为每个结论提供可验证依据。

技能概览：定位、触发词与工作方式

seo-hreflang 是 Claude SEO 项目 25 个子技能之一，负责Hreflang 与国际 SEO（i18n SEO）的审核、校验与生成。它同时支持三种实现载体：HTML link 标签、HTTP 响应头、XML Sitemap。

技能元数据（见 SKILL.md 的 frontmatter）定义了明确的触发条件：当用户提及 "hreflang"、"i18n SEO"、"international SEO"、"multi-language"、"multi-region" 或 "language tags" 时自动激活，也可通过/seo hreflang [url]显式调用，参数提示为[url]。技能采用 MIT 许可，当前版本 2.2.0。

从项目全局看，该技能在 skills/seo/SKILL.md 的命令表中登记为/seo hreflang [url]，对应 "Hreflang/i18n SEO audit and generation"；docs/COMMANDS.md 给出了完整的调用示例与能力清单。值得注意的是，项目在docs/COMMANDS.md中明确将其归为"quick validation"类轻量技能——即聚焦单页/单站点的 hreflang 校验，而非大规模批量抓取。

技能的工作流可以概括为三条主线：

1. 验证（Validate）：对现有 hreflang 实现执行 8 项规则校验；
2. 生成（Generate）：为缺失或错误的实现输出正确代码（HTML / HTTP 头 / Sitemap XML）；
3. 深化（Deepen）：超越纯技术校验，评估文化适应性、内容一致性与本地化格式。

八项核心校验规则

技能文档定义了 8 项必须逐条检查的规则，任何一项失败都会削弱甚至使 hreflang 信号失效。下面逐条展开，并给出严重度与修复要点。

1. 自引用标签（Self-Referencing Tags）

• 每个页面必须包含一个指向自身 URL的 hreflang 标签；
• 自引用 URL 必须与页面 canonical URL完全一致；
• 缺少自引用标签会导致 Google忽略整个 hreflang 集合（而非仅该页面）。

这一点是新手最容易踩的坑：很多人只在非默认语言页面上加了 hreflang，却忘了给页面自己加回引用。正确做法是所有语言版本（包括默认语言）的<head>中都要有指向自身的<link rel="alternate" hreflang="xx" href="自身URL">。

2. 返回标签（Return Tags）

• 如果页面 A 通过 hreflang 指向页面 B，页面 B 必须回指页面 A；
• 每个 hreflang 关系必须是双向的（A→B 且 B→A）；
• 缺少返回标签会让 hreflang 信号对双方页面都失效；
• 检查所有语言版本是否彼此互链（完整网状结构 full mesh）。

多语言站点最常见的失败模式之一：en-US页面声明了指向fr页面的链接，但fr页面没有返回链接，导致该语言对的关系无效。

3. x-default 标签

• 必填：用于指定语言/地区无法匹配时的回退页面；
• 通常指向语言选择器页面或英文版本；
• 每个 alternate 集合中只能有一个x-default；
• 其他所有语言版本也必须返回链接到 x-default。

x-default 的作用是兜底：当用户浏览器语言、地理位置与任何声明都不匹配时，搜索引擎应展示该回退页面，避免把用户导向错误的语言版本。

4. 语言代码校验

• 必须使用ISO 639-1 双字母代码（如en、fr、de、ja）；
• 常见错误：
  • eng代替en——eng属于 ISO 639-2 三字母代码，hreflang 不合法；
  • jp代替ja——日语正确代码是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——拉丁美洲不是一个国家，应使用具体国家代码；
  • 只有地区没有语言前缀（如-US）。

6. Canonical URL 对齐

• hreflang 标签只能出现在 canonical URL 页面上；
• 如果页面rel=canonical指向别处，该页面上的 hreflang 会被忽略；
• canonical URL 与 hreflang URL 必须完全一致（包括尾部斜杠）；
• 非 canonical 页面不应出现在任何 hreflang 集合中。

7. 协议一致性

• 同一 hreflang 集合内所有 URL 必须使用相同协议（HTTPS 或 HTTP）；
• 混合 HTTP/HTTPS 会导致校验失败；
• HTTPS 迁移后必须同步更新所有 hreflang 标签。

8. 跨域支持

• hreflang 可跨不同域名工作（如 example.com 与 example.de）；
• 跨域 hreflang 要求双方域名都有返回标签；
• 两个域名都需在 Google Search Console 中完成验证；
• 跨域场景推荐使用 Sitemap 方式实现。

常见错误速查表

技能文档汇总了一张 10 项常见错误清单，按严重度分级，可直接作为审核输出的对照模板：

三种实现方法详解

方法一：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>区域。每个页面必须包含所有alternate（包括自身）。

方法二：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 规则下发。适用于无法修改 HTML 内容的资源类型。

方法三：XML Sitemap（大型站点推荐）

适用场景：语言变体众多、跨域部署、或页面数 50+ 的站点。完整示例见下文「Hreflang Sitemap 生成」小节。

方法对比

Hreflang 生成流程

当站点缺少 hreflang 或需要重建实现时，按 7 步流程生成：

1. 检测语言：扫描站点语言指示符（URL 路径、子域名、TLD、HTMLlang属性）；
2. 映射页面等价关系：跨语言/地区匹配对应页面；
3. 校验语言代码：对照 ISO 639-1 与 ISO 3166-1 验证所有代码；
4. 生成标签：为每个页面生成 hreflang 标签（含自引用）；
5. 验证返回标签：确认所有关系双向成立；
6. 添加 x-default：为每个页面集合设置回退页；
7. 输出：生成实现代码（HTML、HTTP 头或 Sitemap XML）。

该流程与 docs/COMMANDS.md 登记的能力一一对应：校验自引用、检查返回标签互惠（A→B 需要 B→A）、验证 x-default 存在性、校验 ISO 语言/地区代码、检查 canonical 对齐、检测 HTTP/HTTPS 协议不匹配、生成 link 标签与 Sitemap XML。

Hreflang Sitemap 生成

带 hreflang 的 Sitemap 完整示例

<?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>条目必须包含全部语言 alternate（包括自身）；
• 每个 alternate 必须作为独立的<url>条目出现，并携带完整集合；
• 单个 Sitemap 文件超过 50,000 个 URL 时必须拆分。

从该示例可清晰看到 full mesh（完整网状）结构：en-US、fr、de、x-default四个条目彼此互指，任何语言版本都不存在单向链接。

输出格式：验证报告与生成产物

Hreflang 验证报告

摘要

• 扫描页面总数：XX
• 检测到的语言变体：XX
• 发现的问题数：XX（Critical: X, High: X, Medium: X, Low: X）

验证结果

生成产物

• HTML<link>标签（若选择 HTML 方法）；
• HTTP 头值（若选择头方法）；
• hreflang-sitemap.xml（若选择 Sitemap 方法）。

建议清单

• 需要新增的缺失实现；
• 需要修正的错误代码；
• 方法迁移建议（例如为支撑规模化从 HTML 迁移到 Sitemap）。

文化适应评估：从「技术正确」到「真正本地化」

技能明确要求：分析多语言站点时，不能止步于技术层面的 hreflang 校验，还必须评估内容是否针对每个目标市场做了文化适配。参考 references/cultural-profiles.md 中预置的 DACH、法语区、西语区、日语四类文化画像。

评估步骤

1. 识别所有语言版本及其目标市场；
2. 加载对应的文化画像；
3. 检查 CTA 是否符合文化预期（直接 vs 间接）；
4. 检查信任信号是否匹配本地习惯（认证、法律页面）；
5. 检查本地化页面上是否残留外国品牌引用；
6. 检查数字/日期/货币格式一致性；
7. 将文化适应问题标记为 Medium 严重度。

输出

每个语言版本给出文化适应评分（0-100）及具体发现。

四类预置文化画像要点

DACH 区（DE, AT, CH）：高度正式，使用 "Sie"；CTA 倾向间接表达（"Jetzt entdecken" 优于 "Jetzt kaufen"）；信任信号依赖认证（TUV、ISO）与数据隐私声明；Impressum 页面为法律强制；数字格式1.000,00，日期DD.MM.YYYY，货币 EUR（DE/AT）/CHF（CH）；品牌替换示例 Walmart → MediaMarkt、Amazon → Otto/Zalando；德文相对英文扩展 +25-35%（需预留更长标题与按钮文本）。

法语区（FR, BE, CA-FR, CH-FR）：中高正式度，"Vous" 为默认，"Tu" 仅限年轻/休闲品牌；CTA 用优雅措辞（"Decouvrir nos solutions" 优于 "Achetez maintenant"）；信任信号强调 "Fabrique en France"、专业认证与媒体报道；法律要求 Mentions legales、CNIL、CGV；数字格式1 000,00（千位用空格），日期DD/MM/YYYY，货币 EUR/CAD/CHF；品牌替换 Walmart → Carrefour、Amazon → Fnac/Cdiscount；扩展 +15-25%。

西语区（ES, LATAM）：正式度因国家而异（西班牙 "Usted" 正式，拉美混合）；CTA 温暖个人化（"Empieza tu viaje" 优于 "Comprar ahora"）；信任信号重视社区证明、家庭/关系主题、名人背书；法律：西班牙 LOPD，拉美各国法规不同；数字格式西班牙1.000,00（拉美因国而异）；品牌替换 Walmart → Mercadona（ES）/Coppel（MX）、Amazon → MercadoLibre；扩展 +15-25%。

日语（JA）：非常高的正式度，商务场景要求敬语（Keigo）；幽默含蓄，B2B 避免直白幽默，B2C 可接受 Kawaii 元素；CTA 含蓄礼貌（"Otoiawase" 咨询，优于直接 "buy now"）；信任信号依赖公司经营年限、ISO 认证、权威机构背书；法律：APPI、Tokutei Shotorihiki；数字格式1,000（多数场景无小数），日期YYYY/MM/DD或YYYY年MM月DD日，货币 JPY（无小数）；品牌替换 Amazon → Rakuten；日文相对英文收缩 -10-25%（日文更紧凑）。

默认画像（未收录语言）

当目标语言无预置画像时，按 7 步通用流程评估：研究正式/非正式语域（如韩语有 7 级敬语）→ 检查文字方向（LTR vs RTL，如阿拉伯语、希伯来语、波斯语、乌尔都语）→ 用 CLDR 验证数字/日期格式 → 调研法律要求（隐私法、工商注册、消费者保护）→ 检查文字扩展比率（日耳曼/斯拉夫语系扩展，CJK 收缩）→ 验证货币与支付偏好 → 研究颜色文化含义。

内容一致性审计（Content Parity Audit）

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

对站点或本地内容目录中所有语言版本进行内容一致性审计，完整方法论与评分机制见 references/content-parity.md。

检查维度（对齐矩阵）

新鲜度追踪（防陈旧翻译）

通过三类信号检测过期翻译：文件修改时间戳（EN 更新后 DE 未更新即可能陈旧）、frontmatter 日期（跨版本比较date_modified/lastmod）、内容哈希对比（源语言内容哈希自上次翻译后已变化）。

新鲜度分档阈值：

• Fresh（新鲜）：源更新后 7 天内完成翻译 → 正常；
• Aging（老化）：距源更新 8-30 天 → 低优先级更新；
• Stale（陈旧）：31-90 天 → 中优先级更新；
• Outdated（过期）：90 天以上 → 高优先级更新。

字数比率校验

相对英文源文的期望字数比率：

判定逻辑：德文翻译比英文原文还短，很可能缺失内容；日文翻译比英文还长，很可能存在不必要的冗余填充。

文化适配质量门（Quality Gates）

一致性评分计算（满分 100）

• 页面存在性一致性：30 分
• SEO 元素一致性（标题、meta、schema）：30 分
• 内容结构一致性（章节、图片、FAQ）：25 分
• 新鲜度一致性：15 分

解读区间：90-100 所有语言版本一致性优秀；70-89 良好但有少量缺口；50-69 存在影响部分语言版本的显著问题；低于 50 为重大一致性失败，需立即处理。

输出格式

以矩阵表呈现：

| 页面 | EN | DE | FR | ES | JA | 一致性评分 | |------|----|----|----|----|----|-------------| | /about | ✅ | ✅ | ✅ | ❌ | ✅ | 80/100 | | /pricing | ✅ | ✅ | ⚠️ | ❌ | ❌ | 45/100 |

语言格式校验（Locale Format Validation）

参考 references/locale-formats.md 中按语言环境整理的数字、日期、货币、地址、电话格式对照表。格式不匹配（如德文页面出现美式日期格式）是本地化质量低下的信号，会降低用户信任。

检查项

• 数字格式一致性（如 de-DE 页面应显示 "1.000,00" 而非 "1,000.00"）；
• 日期格式符合语言环境预期；
• 货币符号与位置正确对应目标市场；
• 电话号码使用带正确国家代码的国际格式。

关键格式对照速查

数字格式：en-US/en-GB1,234.56；de-DE/de-AT1.234,56；de-CH1'234.56；fr-FR/fr-CA1 234,56（千位空格）；es-ES1.234,56；es-MX1,234.56；ja-JP1,234；pt-BR1.234,56；ko-KR1,234；zh-CN1,234.56。

日期格式：en-USMM/DD/YYYY；en-GB/fr-FR/es-ES/pt-BRDD/MM/YYYY；de-DEDD.MM.YYYY；ja-JPYYYY/MM/DD或YYYY年MM月DD日；ko-KRYYYY.MM.DD；zh-CNYYYY年MM月DD日。

货币格式：USD/GBP/JPY/KRW/CNY 符号前置；EUR 在德/法/西语区后置且带空格（1.234,56 €）；CHF 前置（CHF 1'234.56）；BRL 前置（R$ 1.234,56）。

地址格式：美国Street, City, State ZIP；英国Street, City, Postcode；德奥Street Nr, PLZ City；法国Street, Code Postal City；日本Postal City District Street（如〒100-0001 東京都千代田区千代田1-1）。

电话格式：美国+1 (512) 555-0123；英国+44 2071 234567；德国+49 30 12345678；法国+33 1 23 45 67 89；日本+81 3-1234-5678。

文字扩展比率（相对英文）：德语 +25-35%、法语/西语/意语/葡语 +15-25%、荷兰语 +10-20%、日语 -10-25%、韩语 -10-20%、中文 -20-30%。

校验规则

1. 扫描页面数字模式（价格、统计、度量衡）；
2. 对照页面声明语言的预期格式；
3. 标记非美页面上的美式数字（如 de-DE 页面的 "$1,234.56"）；
4. 检查博客文章、版权声明、更新时间戳中的日期格式；
5. 验证货币符号与目标市场匹配；
6. 确认电话号码使用正确的国际格式与国家代码。

机器翻译质量门：2025 年 1 月 QRG 的风险信号

references/machine-translation-qa.md 记录了一个重要的政策背景：Google 2025 年 1 月 23 日更新的《质量评估指南》（QRG）在 §4.6.5 明确将未经人工审校的机器翻译内容视为规模化内容滥用（scaled content abuse）的一种形式——"使用自动化工具（生成式 AI 或其他）以低投入方式生产大量几乎无价值的页面"。

关键结论：经母语人工审校并修正的机器翻译是可接受的；而未经审校、或仅做"轻度后期编辑"（仍含幻觉术语、性别/数不一致、未翻译专有名词）的机器翻译输出，会被视为规模化内容滥用。

审计应标记的信号

不应标记的情况

• 明确标注为机器翻译、范围清晰、属于"人工翻译回退模式"的少量 MT 页面（QRG 明确允许诚实标注的 MT）；
• 机器翻译的 UI 字符串——那是 i18n，不是"内容"；
• 无法获取回退信号时的lang="auto"内容（保持保守，不臆断）。

跨技能协作

• 单页 hreflang 校验：留在seo-hreflang技能内；
• 更广泛的规模化内容评分（翻译页熵、正文 AI 模式检测）：转交seo-content技能，通过python3 scripts/content_quality.py执行；
• 检测 Google 自家自动翻译组件：查找.goog-te-banner-frameiframe——自动翻译组件虽被豁免于 MT 规模化内容滥用，但产出内容的可引用性仍然较差。

错误处理与边界场景

技能文档定义了五类典型故障场景的处置策略：

仓库源码级支撑：hreflang 解析实现

除了技能文档本身的规则，项目中存在实际的 hreflang 解析实现，可作为自动化校验的基础：scripts/parse_html.py使用 BeautifulSoup 从 HTML 中抽取 hreflang 信息。

在 scripts/parse_html.py 中，解析逻辑遍历所有rel="alternate"的<link>标签：

# Hreflang for link in soup.find_all("link", rel="alternate"): hreflang = link.get("hreflang") if hreflang: result["hreflang"].append({ "lang": hreflang, "href": link.get("href"), })

解析结果存放在统一的页面数据结构中（parse_html.py 初始化"hreflang": []）。该脚本同时抽取 title、meta description、canonical（parse_html.py 的rel="canonical"）、Open Graph、Twitter Card、schema、标题、内链等信息——其中 canonical 抽取正好支撑第 6 条"Canonical URL 对齐"校验的自动化。

依据 docs/COMMANDS.md 对页面抓取能力的说明，该工具链跟踪的字段包括 title、meta description、canonical、hreflang、Open Graph、schema、标题、内链、robots、sitemap 条目、可索引性、Core Web Vitals、响应状态与重定向链。这意味着你可以用python3 scripts/parse_html.py <url>先抽取页面的 hreflang 原始数据，再对照本指南的 8 项规则做结构化审核，将技能流程与项目脚本打通。

另外从 CHANGELOG.md 可确认该技能的演进脉络：文化画像与一致性审计等增强功能由 Chris Muller 贡献，CHANGELOG.md 记录了 SKILL.md 增加 Cultural Adaptation Assessment、Content Parity Audit、Locale Format Validation 三个章节的版本迭代。

参考文件导航

技能采用按需加载的参考文件设计（启动时不必全部加载），四份配套文档分工如下：

• references/cultural-profiles.md：DACH、法语区、西语区、日语文化适应画像及 Default Profile 通用评估清单；
• references/locale-formats.md：各语言环境的数字、日期、货币、地址、电话格式对照表与校验规则；
• references/content-parity.md：内容一致性审计方法论、对齐矩阵、评分计算与新鲜度阈值；
• references/machine-translation-qa.md：基于 2025 年 1 月 QRG §4.6.5 的机器翻译质量标记清单。

实战落地建议

综合以上内容，将 seo-hreflang 技能用于真实站点时的推荐执行路径：

1. 先抓取后校验：用python3 scripts/parse_html.py <url>抽取 hreflang 与 canonical 原始数据（parse_html.py）；
2. 按 8 项规则逐条比对：自引用 → 返回标签 → x-default → 语言代码 → 地区代码 → canonical 对齐 → 协议一致性 → 跨域支持；
3. 对照 10 项常见错误表定位问题并按严重度排序修复（Critical 优先）；
4. 选择实现载体：变体少用 HTML link，非 HTML 资源用 HTTP 头，大型/跨域站用 Sitemap（注意 50,000 URL 拆分与xmlns:xhtml命名空间）；
5. 超越技术校验：加载文化画像评估 CTA、信任信号、法律引用与格式一致性；
6. 对多语言内容跑一致性审计：核对页面存在性、结构、schema 与字数比率，用新鲜度分档追踪陈旧翻译；
7. 警惕机器翻译风险：对照 QRG 信号清单排查lang不匹配、meta 超长、正文未翻译等规模化内容滥用特征。

按照上述路径，你可以把一个「hreflang 标签有、但质量存疑」的多语言站点，逐步推进到「标签技术正确 + 内容真正本地化 + 无机器翻译滥用风险」的国际 SEO 完整状态。