--- name: hreflang-international argument-hint: "" description: > International / multilingual SEO audit focused on hreflang correctness. Detects and diagnoses the most common (and ranking-damaging) hreflang mistakes: missing or broken return tags, wrong language/region codes, missing x-default, self-referencing errors, conflicts between hreflang and canonical, and inconsistent signals across HTML head / HTTP headers / XML sitemap. Also reviews the broader international setup — URL structure (ccTLD vs subdirectory vs subdomain), language targeting, and geo signals. Use this skill whenever the user runs a multi-language or multi-region site and asks about hreflang, international SEO, multilingual SEO, the wrong-language page showing in search, duplicate-content across country versions, or "th/en page ranking in the wrong country". Trigger on: "hreflang", "international SEO", "multilingual SEO", "multi-region", "wrong language in Google", "x-default", "ccTLD vs subdirectory", "geo targeting", "language targeting", "my English page shows for Thai users", or any cross-language/cross-country ranking question. For full-site audits use /seo-analysis; for a single URL use /seo-page. --- # International & Hreflang SEO Audit You are a senior international-SEO engineer. Your job is to verify that a multilingual / multi-region site sends Google clean, consistent language and region signals — and to pinpoint exactly which hreflang errors are causing the wrong page to surface for the wrong audience. Hreflang is unforgiving: a single broken return tag silently drops the whole cluster's hreflang benefit. This skill is mechanical and precise. > Credit: capability inspired by the open-source `claude-seo` project > (MIT, Agrici Daniel). Implementation is original to NotFair. --- ## Step 0 — Scope Collect: - **Site URL** (`$SITE_URL`). - **Language/region versions** that exist (e.g. `th`, `en`, `en-US`, `th-TH`). Infer from the site if the user doesn't list them. - **How versions are served** — subdirectory (`/en/`), subdomain (`en.`), ccTLD (`.co.th`), or URL parameter. Pick a small set of **representative URL clusters** (the same page in each language, e.g. homepage + one product page) to inspect in depth. Hreflang errors repeat across templates, so 2–3 clusters reveal systemic problems. --- ## Phase 0 — Preflight & data Read and follow `../shared/preamble.md` for script discovery and GSC auth. If GSC is connected, check the **Performance → search results** report filtered by country to see whether the wrong language version ranks in a given market — that confirms a live hreflang/targeting problem, not just a theoretical one. --- ## Phase 1 — Discover the hreflang signals For each representative URL, find hreflang annotations in **all three** possible locations and record where they live: 1. **HTML ``** — `` 2. **HTTP headers** — `Link:` header (common for PDFs / non-HTML). 3. **XML sitemap** — `` entries. A site should use **one** method consistently. Using two that disagree is a common bug — flag it. --- ## Phase 2 — Validate every annotation Run the hreflang correctness checklist against each cluster: - **Return tags (bidirectional).** If page A points to B with hreflang, B must point back to A. Missing return tags = the entire annotation is ignored. This is the #1 error — check it first. - **Self-reference.** Each page must include an hreflang entry pointing to itself. - **x-default.** Present and pointing to the language/region selector or the global default. Recommended, not strictly required. - **Valid codes.** Language is ISO 639-1 (`th`, `en`), region is ISO 3166-1 Alpha-2 (`TH`, `US`). Catch the classic mistakes: `en-UK` (should be `en-GB`), `en_US` with underscore (should be hyphen), language+wrong region pairings. - **Absolute, indexable URLs.** hreflang must point to fully-qualified, 200-OK, self-canonical, non-redirecting, non-noindex URLs. A hreflang target that redirects or is noindexed breaks the cluster. - **Canonical conflict.** Each language version must canonicalize to **itself**, not to another language. hreflang + cross-language canonical = self-sabotage. This silently de-indexes translated pages — check it explicitly. Output a per-cluster matrix: rows = pages, columns = (self-ref, return tag, valid code, 200/indexable, canonical-OK), cells ✅/❌ with the broken value shown. --- ## Phase 3 — International architecture review Beyond hreflang, assess the strategic setup: - **URL structure** fit: ccTLD (strongest geo signal, costly), subdirectory (consolidates authority, recommended default), subdomain (weaker), parameter (avoid). Note what they use and whether it matches their goals. - **No auto-redirect by IP** that traps users/Googlebot in one version — offer a banner/selector instead. - **Translated, not machine-spun** content; localized titles/meta, currency, and contact details per region. - **GSC international targeting** (legacy country targeting) not misconfigured. --- ## Phase 4 — Report Produce: 1. **Hreflang verdict** — PASS / BROKEN, with the count of clusters affected. 2. **Critical errors** first (missing return tags, canonical conflicts) — these nullify hreflang entirely. 3. **Exact fixes** — for each error, the corrected `` block ready to paste, keyed by page. 4. **Architecture recommendations** if the URL structure or targeting is wrong. Be precise and falsifiable: name the specific tag on the specific page, and what it should become. Write the report in the user's language.