seo-international
installsforks
How to install seo-international?
hainrixz/claude-seo-ai/seo-international
$npx -y skills add Hainrixz/claude-seo-ai --skill seo-internationalAudit and generate hreflang annotations for multilingual sites — check reciprocity, BCP-47 validity, self-reference, x-default, hreflang/canonical conflicts, and <html lang> agreement, and emit reciprocal hreflang link sets. Module M20 (conditional). Feeds the Search SEO score.
SKILL.md
| 1 | # seo-international (M20) |
| 2 | |
| 3 | hreflang tells search engines which language/region URL to serve. This module is **conditional**: it only runs when seo-vertical-detect flags a multilingual site (multiple `lang`/locale URLs, language switcher, or existing hreflang). On monolingual sites every finding is `not_applicable` at severity 0. Schema-type concerns defer to `references/schema-tier1.md`; this module owns link-level localization only. |
| 4 | |
| 5 | ## Audits |
| 6 | Working from the PageSnapshot (`rendered_dom` if present, else `raw_html`). Read hreflang from `<link rel="alternate" hreflang="...">` in `<head>` (also accept HTTP `Link:` headers / sitemap `xhtml:link` when present): |
| 7 | 1. **Reciprocity** — if page A declares an alternate B, B must declare A back. One-way hreflang is ignored by Google. |
| 8 | 2. **BCP-47 validity** — each `hreflang` value is a valid language (`en`) or language-region (`en-GB`, `pt-BR`) tag; region is ISO-3166-1 alpha-2, not a country-of-language guess (`en-UK` is invalid; use `en-GB`). |
| 9 | 3. **Self-reference** — the page lists itself in its own hreflang set. |
| 10 | 4. **x-default** — at least one `hreflang="x-default"` for the language-selector / fallback URL. |
| 11 | 5. **hreflang↔canonical conflict** — an hreflang URL must be self-canonical; pointing hreflang at a URL whose `rel=canonical` is a *different* page neutralizes the cluster (cross-check M2/seo-indexability). |
| 12 | 6. **`<html lang>` agreement** — the document `lang` attribute matches the locale this URL targets in its own hreflang entry. |
| 13 | |
| 14 | ## Fixes |
| 15 | - **AUTO** (`fixable: auto`): when the locale→URL map is **known** (supplied by the user, a sitemap, or discovered alternates), generate a complete reciprocal hreflang link set — every locale + a single `x-default` — as a `<head>` diff for `fix`. Additive and deterministic. |
| 16 | - **PROPOSED** (`fixable: proposed`): a partial set inferred from discovered alternates that needs the user to confirm the locale map before write. |
| 17 | - **ADVISORY** (`fixable: advisory`): "this looks multilingual but no locale map exists" — never written by the tool. |
| 18 | - **Never fabricate** locales, region codes, or alternate URLs. If the map is incomplete, leave a clearly-marked `TODO(locale)` placeholder and ask the user. |
| 19 | |
| 20 | ## Verification |
| 21 | - Offline: `node ${CLAUDE_SKILL_DIR}/../../scripts/hreflang-check.mjs --url <u>` — parses the alternate set, validates BCP-47 tags, and checks reciprocity/self-reference/x-default across the discovered cluster. |
| 22 | - Reciprocity requires fetching each declared alternate; when those URLs (or a sitemap tier) are unavailable, status is `needs_api`, **never** a false `pass`. |
| 23 | |
| 24 | ## Findings |
| 25 | Findings conform to `schema/finding.schema.json`. On a confirmed multilingual site severity is **4**; otherwise the check is `not_applicable` at severity 0. Examples: |
| 26 | - `M20.hreflang.missing_reciprocal` — page declares `hreflang="de-DE"` for a URL that does not point back (`status: fail`, severity 4, `fixable: proposed`, axis `search`, confidence `established`). `evidence.observed` quotes the one-way `<link>`; `verification.reproduce` runs the hreflang-check command above. |
| 27 | - `M20.hreflang.invalid_bcp47` — `hreflang="en-UK"` (`fail`, severity 4, `fixable: auto`, axis `search`, confidence `established`; recommend `en-GB`). |
| 28 | - `M20.hreflang.missing_xdefault` — cluster has no `x-default` fallback (`warn`, severity 4, `fixable: auto`, axis `search`, confidence `directional`). |
| 29 | - `M20.hreflang.not_applicable` — monolingual site (`not_applicable`, severity 0). |
| 30 | |
| 31 | ## Honesty |
| 32 | - hreflang is a **targeting/clustering** signal, not a ranking boost: it selects which existing URL to show in a locale, it does not raise rankings. Don't sell it as a ranking lever. |
| 33 | - hreflang does **not** fix thin or machine-translated content, and it is not a substitute for `rel=canonical` — the two work together. |
| 34 | - Bing/Yandex use it weakly to not-at-all; the documented beneficiary is Google. Don't claim cross-engine parity. |
People who liked this also viewed
6 picksType
- seo-auditWhen the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tagSkillsJul 2026
- copywritingWhen the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user sSkillsJul 2026
- marketing-psychologyWhen the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,'SkillsJul 2026
- content-strategyWhen the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "conSkillsJul 2026
- programmatic-seoWhen the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "directory pages," "location pSkillsJul 2026
- marketing-ideasWhen the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing stratSkillsJul 2026
