‹ 首页

seo-hreflang

@seranking · 收录于 1 周前

Hreflang and international SEO audit for multi-language and multi-region sites. Validates language-region codes, return tags, x-default, canonical alignment, and conflict detection across the per-URL HTML, the SE Ranking audit, and the XML sitemap. Use when the user asks "hreflang", "international SEO", "i18n", "language targeting", "x-default", "regional sites", or "multi-language SEO".

场景多语言网站国际seo网站审计

适合你，如果你运营多语言或多地区网站，需要确保 hreflang 配置正确。

/ 下载安装
seo-hreflang.skill双击,或拖进 Claude 桌面版 / Cowork,即完成安装↓ .skill↓ .zip
用别的 agent?下载 .zip 解压,把文件夹放进它的技能目录
Claude Code~/.claude/skills/(项目级 .claude/skills/)
Codex CLI~/.codex/skills/
Cursor自动读取上面两处目录
其他工具见其文档的「skills」目录;两个下载是同一份文件,只是名字不同
/ 通过 npx 安装 校验哈希
npx oh-my-skill add seranking/seo-skills/seo-hreflang
/ 通过 bash 安装
curl -fsSL https://oh-my-skill.com/install.sh | bash -s -- seranking/seo-skills/seo-hreflang
/ 已经装过?验证本机副本,不用重装
npx oh-my-skill verify seranking/seo-skills/seo-hreflang
安装目标可用 --agent / --scope 或 --to 明确指定;省略时只会在唯一已存在的 agent 目录上自动选择,零命中或多命中会停止并提示。content_hash 缺失或不一致均拒装。
85GitHub stars
~3K最小装载
~4.4K含声明引用
~4.4K文本包总量
镜像托管

怎么用

技能原文 SKILL.md作者撰写 · MIT · fd6d140
Example output: [examples/seo-hreflang-airbnb-com-20260514/HREFLANG-REPORT.md](../../examples/seo-hreflang-airbnb-com-20260514/HREFLANG-REPORT.md)

Hreflang Audit

Adapted from AgriciDaniel/claude-seo's seo-hreflang skill (MIT). Concept and validation rules originate there; this implementation is rebuilt against our backend (SE Ranking MCP + Firecrawl + WebFetch + Google APIs via seo-google).

Validate hreflang implementations on a multi-language or multi-region site. Surface SE Ranking audit-level hreflang issues, parse a sample of pages for the actual <link rel="alternate" hreflang="…"> tags they emit, cross-check the sitemap, and produce one of three verdicts — PASS, NEEDS-FIX, or BROKEN — with a top-fixes table anchored in objective signals.

Prerequisites
  • SE Ranking MCP server connected.
  • Claude's WebFetch tool available (fallback when Firecrawl is unavailable).
  • User provides: a target domain (e.g. example.com). Optional: explicit list of representative pages to inventory; explicit sitemap URL if not at /sitemap.xml.
  • Predecessor (recommended): seo-technical-audit or seo-sitemap already run on this domain. Without an existing audit, the skill creates one (which costs significantly more credits).
Process
  1. Validate target & preflight. See skills/seo-firecrawl/references/preflight.md for the canonical 3-stage preflight (credit balance, Firecrawl availability, Google APIs). Skill-specific notes:
  2. Normalise domain (strip protocol, trailing slash) before continuing.
  3. Estimated SE Ranking cost for this skill: ~5–10 SE Ranking credits for re-using an existing audit (up to ~3 Firecrawl credits for the per-URL inventory).
  4. Firecrawl: optional with WebFetch fallback, ~6 Firecrawl credits if available (hard cap). When available, step 4 (per-URL hreflang inventory) runs on homepage + 5 representative pages with formats: ["rawHtml"]. Without Firecrawl, step 4 falls back to WebFetch — coverage is degraded because WebFetch returns markdown only and silently strips <link rel="alternate"> tags from <head>. Pass --no-firecrawl to force WebFetch even when Firecrawl is available.
  5. Google APIs: tier 1 (GSC) unlocks step 6 (GSC verification of hreflang-targeted alternates). See skills/seo-google/references/cross-skill-integration.md for the full enrichment contract.
  1. Find or refresh the audit DATA_listAudits → DATA_getAuditStatus
  2. List audits for the domain. If a recent audit exists (<30 days), use it.
  3. If older than 30 days, run DATA_recheckAudit and wait for done.
  4. If none exists, ask the user before creating one with DATA_createStandardAudit — it consumes credits.
  1. Pull SE Ranking's hreflang findings DATA_getAuditReport + DATA_getAuditPagesByIssue
  2. SE Ranking's audit catches hreflang errors directly — surface them first as ground truth.
  3. From DATA_getAuditReport, extract every issue with code or category matching hreflang (typical codes: hreflang_no_return_tag, hreflang_invalid_lang_code, hreflang_conflict, hreflang_missing_x_default, hreflang_canonical_mismatch, hreflang_no_self_reference).
  4. For each significant hreflang issue (count ≥ 1), call DATA_getAuditPagesByIssue to enumerate the affected URLs.
  5. Persist to 01-audit-hreflang-issues.md and feed into hreflang-issues.csv.
  1. Per-URL hreflang tag inventory mcp__firecrawl-mcp__firecrawl_scrape (preferred) / WebFetch (fallback)
  2. Sample selection: homepage + up to 5 representative pages from DATA_getDomainPages (sort by traffic descending; bias toward pages on different language paths if the URL structure exposes them — /en/, /fr/, /de/, etc.).
  3. Firecrawl path (1 credit per URL, ~6 total): call firecrawl_scrape(url=..., formats=["rawHtml"]). Pin rawHtml — the default html post-processing strips <link rel="alternate"> on many sites. Parse every <link rel="alternate" hreflang="…" href="…"> from the <head>. Capture: source URL, hreflang attribute, href, and whether it's self-referencing.
  4. WebFetch fallback (no Firecrawl): try fetching each URL and extracting hreflang from the markdown response. WebFetch frequently returns markdown that has stripped <head> link tags, so this path will under-report. Note in HREFLANG-REPORT.md: Per-URL inventory: degraded coverage — Firecrawl not installed; some hreflang tags may be missed.
  5. Apply validation rules (see references/validation-rules.md for the full list):
  6. Self-referencing tag: the page's own URL must appear in its own hreflang set.
  7. Return tags: every alternate link must reciprocate. If page A lists B as fr, page B must list A as en (or whichever).
  8. x-default: at least one alternate per set must use hreflang="x-default".
  9. Language-region code validation: every value must be a valid ISO 639-1 language (optionally followed by - and an ISO 3166-1 Alpha-2 region). Common errors caught: eng (use en), jp (use ja), en-uk (use en-GB), es-LA (no such ISO region).
  10. Conflict detection: the same hreflang value (e.g. de-DE) appearing on multiple distinct URLs is a conflict — Google ignores conflicting sets.
  11. Canonical alignment: if the page has <link rel="canonical">, it must match the page's own URL (or its self-referencing hreflang URL). Hreflang on a non-canonical page is silently ignored by Google.
  12. Protocol consistency: all URLs in a set must share the same scheme (HTTPS preferred).
  13. Persist to 02-per-url-hreflang.md and append findings to hreflang-issues.csv.
  1. Sitemap-level hreflang (defer to seo-sitemap where appropriate)
  2. If the user's domain uses sitemap-based hreflang (<xhtml:link rel="alternate" …> inside the sitemap), this skill checks structure and consistency only. Full sitemap analysis (orphans, missing pages, broken entries) is seo-sitemap's job — recommend it explicitly if a sitemap-vs-audit diff is in scope.
  3. Fetch the sitemap. Try https://{domain}/sitemap.xml; if 404, fetch /robots.txt and find Sitemap: directives. For sitemap-of-sitemaps, recursively fetch each child.
  4. Validate hreflang within the sitemap:
  5. Does the sitemap use the xmlns:xhtml="http://www.w3.org/1999/xhtml" namespace? Required for hreflang in sitemaps.
  6. Does each <url> entry that has hreflang alternates include itself in the alternate set (self-reference)?
  7. Does every alternate listed in one <url> entry reciprocate as its own <url> entry with the same alternate set (return tags)?
  8. Are language-region codes valid (apply same rules as step 4)?
  9. Cross-check against per-URL inventory (step 4): if a sample URL's HTML lists 4 hreflang alternates but the sitemap entry for that URL lists 6, that mismatch is a conflict — Google may pick either, and inconsistency degrades the signal.
  10. Persist to 03-sitemap-hreflang.md and append findings to hreflang-issues.csv.
  1. GSC verification of hreflang-targeted alternates (only if google-api.json is present, tier ≥ 1)
  2. For each unique domain that appears as an href target in the hreflang sets (e.g. example.com, example.de, example.fr), confirm GSC verification: python3 scripts/gsc_query.py --property "{property}" --json (a status-only check; just confirm the property responds without PROPERTY_NOT_VERIFIED).
  3. Why this matters: Google explicitly recommends verifying every domain that participates in a cross-domain hreflang setup. If example.de is listed as an alternate but isn't verified in this account, the hreflang signal is weakened and you can't see how Google interprets it.
  4. Surface in HREFLANG-REPORT.md as a section "## GSC verification of hreflang targets" with one row per target domain: verified / not verified / not configured.
  5. If property not verified for a target domain: list it as a fix at Medium severity ("Verify {domain} in Google Search Console — required for cross-domain hreflang trust").
  6. See skills/seo-google/references/cross-skill-integration.md § "Trigger pattern" for the failure-mode contract.
  1. Synthesise verdict
  2. Apply the verdict heuristic (see Tips) to produce PASS, NEEDS-FIX, or BROKEN.
  3. Sort hreflang-issues.csv by severity descending, then count descending.
  4. Write HREFLANG-REPORT.md with the top-fixes table (top 10) and the verdict.
Output format

Create a folder seo-hreflang-{target-slug}-{YYYYMMDD}/ with:

seo-hreflang-{target-slug}-{YYYYMMDD}/
├── 01-audit-hreflang-issues.md   (SE Ranking audit findings filtered to hreflang)
├── 02-per-url-hreflang.md         (per-URL <link rel="alternate"> inventory + validation findings)
├── 03-sitemap-hreflang.md         (sitemap-level hreflang validation; defer details to seo-sitemap)
├── evidence/
│   ├── homepage-rawhtml.html      (raw HTML from Firecrawl, for the homepage sample)
│   ├── sample-{n}-rawhtml.html    (raw HTML for each sampled URL)
│   └── sitemap.xml                (raw fetched sitemap)
├── hreflang-issues.csv            (load-bearing: URL, issue code, severity, fix)
└── HREFLANG-REPORT.md             (PRIMARY: verdict + top fixes table)

HREFLANG-REPORT.md follows this shape:

# Hreflang Audit: {domain}

> Audit date {YYYY-MM-DD} · Sample size: {n} URLs · Languages detected: {comma-separated list}

## Verdict: {PASS | NEEDS-FIX | BROKEN}

Reasoning: {1–2 sentences anchored in concrete numbers from the data}.

## Summary

| Source | Findings | Severity breakdown |
|---|---|---|
| SE Ranking audit | {n} | Critical: {n} · High: {n} · Medium: {n} · Low: {n} |
| Per-URL HTML inventory | {n} | … |
| Sitemap | {n} | … |

## Top fixes (impact-ranked)

| # | URL | Issue | Severity | Fix |
|---|---|---|---|---|
| 1 | {URL} | {issue code} | {severity} | {one-line fix} |
| 2 | … | … | … | … |
| ... up to 10 |

## Languages detected

| Language | URL count | Self-ref OK | Return tags OK | x-default OK |
|---|---|---|---|---|
| en-US | {n} | ✓ / ✗ {count} | ✓ / ✗ | ✓ / ✗ |
| de-DE | {n} | … | … | … |
| ... |

## Per-URL inventory ({n} URLs sampled)

| URL | Alternates | Self-ref | x-default | Notable issues |
|---|---|---|---|---|
| {URL} | {n} | ✓/✗ | ✓/✗ | {short text} |
| ... |

## Sitemap-level hreflang
- xhtml namespace declared: {✓/✗}
- URLs with hreflang alternates: {n}
- Self-reference within sitemap: {✓ all / ✗ {count} missing}
- Return tags within sitemap: {✓ all / ✗ {count} missing}
- Per-URL HTML vs sitemap consistency: {✓ all match / ✗ {count} mismatched}
- Full sitemap-vs-audit analysis: see `seo-sitemap` (orphans, broken entries, lastmod).

## GSC verification of hreflang targets

| Domain | Verified | Notes |
|---|---|---|
| {domain1} | ✓ / ✗ | {note if unverified} |
| ... |

(Or: `GSC verification: not configured (run bash extensions/google/install.sh)`.)

## Coverage notes

- Per-URL inventory tool: {Firecrawl rawHtml | WebFetch fallback (degraded — some hreflang tags may be missed)}.
- Pages sampled: homepage + {n} representative pages (selection: top traffic from `DATA_getDomainPages`).

## Apply

- Walk `hreflang-issues.csv` row-by-row; each row is one specific change (URL + issue + fix).
- After applying changes, re-run `seo-technical-audit` to refresh SE Ranking's findings, then re-run this skill to verify.

hreflang-issues.csv columns: url,issue_code,severity,fix,source where source is one of audit | html | sitemap | gsc.

Tips
  • Respect SE Ranking Data API rate limit: 10 req/sec.
  • Reuse existing audits when possible — creating a new audit is by far the most expensive operation in this skill.
  • Verdict heuristic:
  • PASS: zero Critical findings; ≤ 2 High findings; sample URLs all have self-reference, x-default, and reciprocal return tags; all language-region codes valid; canonical aligns with self-ref hreflang.
  • NEEDS-FIX: any High finding; or > 5 Medium findings; or any one of (missing x-default, missing return tags on > 25% of sampled pages, language-region code error, sitemap-vs-HTML mismatch).
  • BROKEN: any Critical finding; or hreflang attempted but no self-reference on the homepage; or canonical pointing elsewhere on a page that nonetheless emits hreflang (entire set is ignored by Google); or > 50% of sampled URLs missing return tags.
  • Anchor every claim in HREFLANG-REPORT.md to a row in hreflang-issues.csv. If a stakeholder questions the verdict, walk them through the CSV.
  • For sites with > 50 language variants per page, the per-URL HTML implementation bloats the <head> — recommend the sitemap-based implementation instead. Don't generate code; the deliverable is diagnostic, not code-gen.
  • The skill does not assess cultural adaptation, content parity, or locale formatting. Those are translation/QA concerns; they're orthogonal to whether hreflang itself is technically correct. If the user wants those, point them at the translation team — this skill answers "is the technical hreflang signal working?", not "is the localised content good?".
  • For cross-domain hreflang (e.g. example.com ↔ example.de), step 6's GSC check is the highest-value enrichment — verifying both domains is Google's explicit recommendation.
  • Common false-positive guard: if a sampled page legitimately has no internationalization (e.g. a single-region site), zero hreflang tags is correct, not an issue. The skill detects this by checking whether any sampled page emits hreflang; if none do, the verdict is PASS with note "No hreflang implementation detected — single-language site."
  • Pair with seo-sitemap for the sitemap-vs-audit diff; pair with seo-technical-audit for full technical health. This skill is narrow: hreflang correctness only.
  • See references/validation-rules.md for the full per-issue rule table (severity, detection logic, suggested fix).
按 MIT 许可原样转载,未经改动 · 在 GitHub 查看 →

评论

登录即可评论;带「已验证安装」的,是发布者名下有本店的安装或持有记录。
…