{"id":"2448b567-e826-44ac-b3d6-ec425cc3e81f","shortId":"paFunE","kind":"skill","title":"seo-hreflang","tagline":"Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang implementations. Use when user says \"hreflang\", \"i18n SEO\", \"international SEO\", \"multi-language\", \"multi-region\", or \"langua","description":"# Hreflang & International SEO\n\n## When to Use\n- Use when validating or generating hreflang for multilingual or multiregional sites.\n- Use when the user mentions international SEO, language tags, x-default, or hreflang issues.\n- Use when auditing locale alternates across HTML, headers, or sitemap implementations.\n\nValidate existing hreflang implementations or generate correct hreflang tags\nfor multi-language and multi-region sites. Supports HTML, HTTP header, and\nXML sitemap implementations.\n\n## Validation Checks\n\n### 1. Self-Referencing Tags\n- Every page must include an hreflang tag pointing to itself\n- The self-referencing URL must exactly match the page's canonical URL\n- Missing self-referencing tags cause Google to ignore the entire hreflang set\n\n### 2. Return Tags\n- If page A links to page B with hreflang, page B must link back to page A\n- Every hreflang relationship must be bidirectional (A→B and B→A)\n- Missing return tags invalidate the hreflang signal for both pages\n- Check all language versions reference each other (full mesh)\n\n### 3. x-default Tag\n- Required: designates the fallback page for unmatched languages/regions\n- Typically points to the language selector page or English version\n- Only one x-default per set of alternates\n- Must also have return tags from all other language versions\n\n### 4. Language Code Validation\n- Must use ISO 639-1 two-letter codes (e.g., `en`, `fr`, `de`, `ja`)\n- Common errors:\n  - `eng` instead of `en` (ISO 639-2, not valid for hreflang)\n  - `jp` instead of `ja` (incorrect code for Japanese)\n  - `zh` without region qualifier (ambiguous; use `zh-Hans` or `zh-Hant`)\n\n### 5. Region Code Validation\n- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g., `en-US`, `en-GB`, `pt-BR`)\n- Format: `language-REGION` (lowercase language, uppercase region)\n- Common errors:\n  - `en-uk` instead of `en-GB` (UK is not a valid ISO 3166-1 code)\n  - `es-LA` (Latin America is not a country; use specific countries)\n  - Region without language prefix\n\n### 6. Canonical URL Alignment\n- Hreflang tags must only appear on canonical URLs\n- If a page has `rel=canonical` pointing elsewhere, hreflang on that page is ignored\n- The canonical URL and hreflang URL must match exactly (including trailing slashes)\n- Non-canonical pages should not be in any hreflang set\n\n### 7. Protocol Consistency\n- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)\n- Mixed HTTP/HTTPS in hreflang sets causes validation failures\n- After HTTPS migration, update all hreflang tags to HTTPS\n\n### 8. Cross-Domain Support\n- Hreflang works across different domains (e.g., example.com and example.de)\n- Cross-domain hreflang requires return tags on both domains\n- Verify both domains are verified in Google Search Console\n- Sitemap-based implementation recommended for cross-domain setups\n\n## Common Mistakes\n\n| Issue | Severity | Fix |\n|-------|----------|-----|\n| Missing self-referencing tag | Critical | Add hreflang pointing to same page URL |\n| Missing return tags (A→B but no B→A) | Critical | Add matching return tags on all alternates |\n| Missing x-default | High | Add x-default pointing to fallback/selector page |\n| Invalid language code (e.g., `eng`) | High | Use ISO 639-1 two-letter codes |\n| Invalid region code (e.g., `en-uk`) | High | Use ISO 3166-1 Alpha-2 codes |\n| Hreflang on non-canonical URL | High | Move hreflang to canonical URL only |\n| HTTP/HTTPS mismatch in URLs | Medium | Standardize all URLs to HTTPS |\n| Trailing slash inconsistency | Medium | Match canonical URL format exactly |\n| Hreflang in both HTML and sitemap | Low | Choose one method (sitemap preferred for large sites) |\n| Language without region when needed | Low | Add region qualifier for geo-targeted content |\n\n## Implementation Methods\n\n### Method 1: HTML Link Tags\nBest for: Sites with <50 language/region variants per page.\n\n```html\n<link rel=\"alternate\" hreflang=\"en-US\" href=\"https://example.com/page\" />\n<link rel=\"alternate\" hreflang=\"en-GB\" href=\"https://example.co.uk/page\" />\n<link rel=\"alternate\" hreflang=\"fr\" href=\"https://example.com/fr/page\" />\n<link rel=\"alternate\" hreflang=\"x-default\" href=\"https://example.com/page\" />\n```\n\nPlace in `<head>` section. Every page must include all alternates including itself.\n\n### Method 2: HTTP Headers\nBest for: Non-HTML files (PDFs, documents).\n\n```\nLink: <https://example.com/page>; rel=\"alternate\"; hreflang=\"en-US\",\n      <https://example.com/fr/page>; rel=\"alternate\"; hreflang=\"fr\",\n      <https://example.com/page>; rel=\"alternate\"; hreflang=\"x-default\"\n```\n\nSet via server configuration or CDN rules.\n\n### Method 3: XML Sitemap (Recommended for large sites)\nBest for: Sites with many language variants, cross-domain setups, or 50+ pages.\n\nSee Hreflang Sitemap Generation section below.\n\n### Method Comparison\n| Method | Best For | Pros | Cons |\n|--------|----------|------|------|\n| HTML link tags | Small sites (<50 variants) | Easy to implement, visible in source | Bloats `<head>`, hard to maintain at scale |\n| HTTP headers | Non-HTML files | Works for PDFs, images | Complex server config, not visible in HTML |\n| XML sitemap | Large sites, cross-domain | Scalable, centralized management | Not visible on page, requires sitemap maintenance |\n\n## Hreflang Generation\n\n### Process\n1. **Detect languages**: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)\n2. **Map page equivalents**: Match corresponding pages across languages/regions\n3. **Validate language codes**: Verify all codes against ISO 639-1 and ISO 3166-1\n4. **Generate tags**: Create hreflang tags for each page including self-referencing\n5. **Verify return tags**: Confirm all relationships are bidirectional\n6. **Add x-default**: Set fallback for each page set\n7. **Output**: Generate implementation code (HTML, HTTP headers, or sitemap XML)\n\n## Hreflang Sitemap Generation\n\n### Sitemap with Hreflang\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\"\n        xmlns:xhtml=\"http://www.w3.org/1999/xhtml\">\n  <url>\n    <loc>https://example.com/page</loc>\n    <xhtml:link rel=\"alternate\" hreflang=\"en-US\" href=\"https://example.com/page\" />\n    <xhtml:link rel=\"alternate\" hreflang=\"fr\" href=\"https://example.com/fr/page\" />\n    <xhtml:link rel=\"alternate\" hreflang=\"de\" href=\"https://example.de/page\" />\n    <xhtml:link rel=\"alternate\" hreflang=\"x-default\" href=\"https://example.com/page\" />\n  </url>\n  <url>\n    <loc>https://example.com/fr/page</loc>\n    <xhtml:link rel=\"alternate\" hreflang=\"en-US\" href=\"https://example.com/page\" />\n    <xhtml:link rel=\"alternate\" hreflang=\"fr\" href=\"https://example.com/fr/page\" />\n    <xhtml:link rel=\"alternate\" hreflang=\"de\" href=\"https://example.de/page\" />\n    <xhtml:link rel=\"alternate\" hreflang=\"x-default\" href=\"https://example.com/page\" />\n  </url>\n</urlset>\n```\n\nKey rules:\n- Include the `xmlns:xhtml` namespace declaration\n- Every `<url>` entry must include ALL language alternates (including itself)\n- Each alternate must appear as a separate `<url>` entry with its own full set\n- Split at 50,000 URLs per sitemap file\n\n## Output\n\n### Hreflang Validation Report\n\n#### Summary\n- Total pages scanned: XX\n- Language variants detected: XX\n- Issues found: XX (Critical: X, High: X, Medium: X, Low: X)\n\n#### Validation Results\n| Language | URL | Self-Ref | Return Tags | x-default | Status |\n|----------|-----|----------|-------------|-----------|--------|\n| en-US | https://... | ✅ | ✅ | ✅ | ✅ |\n| fr | https://... | ❌ | ⚠️ | ✅ | ❌ |\n| de | https://... | ✅ | ❌ | ✅ | ❌ |\n\n### Generated Hreflang Tags\n- HTML `<link>` tags (if HTML method chosen)\n- HTTP header values (if header method chosen)\n- `hreflang-sitemap.xml` (if sitemap method chosen)\n\n### Recommendations\n- Missing implementations to add\n- Incorrect codes to fix\n- Method migration suggestions (e.g., HTML to sitemap for scale)\n\n## Error Handling\n\n| Scenario | Action |\n|----------|--------|\n| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again. |\n| No hreflang tags found | Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method. |\n| Invalid language/region codes detected | List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement. |\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.","tags":["seo","hreflang","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows"],"capabilities":["skill","source-sickn33","skill-seo-hreflang","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/seo-hreflang","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34515 github stars · SKILL.md body (8,774 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T12:51:44.273Z","embedding":null,"createdAt":"2026-04-18T21:44:32.384Z","updatedAt":"2026-04-22T12:51:44.273Z","lastSeenAt":"2026-04-22T12:51:44.273Z","tsv":"'-1':252,306,344,545,561,824,828 '-2':270,308,563 '/fr/page':678,885 '/page':669,685,882 '000':919 '1':111,629,790 '2':152,655,805 '3':202,700,814 '3166':305,343,560,827 '4':244,829 '5':296,842 '50':637,719,739,918 '6':362,851 '639':251,269,544,823 '7':411,862 '8':445 'absenc':1039 'across':77,452,812 'action':1008 'add':499,516,528,618,852,991 'align':365 'alpha':307,562 'also':235 'altern':76,233,522,651,671,680,687,900,904 'ambigu':287 'america':350 'appear':370,906 'appropri':1051 'ask':1109 'attribut':804 'audit':8,74 'b':161,165,179,181,510,513 'back':168 'base':480 'best':633,658,707,730 'bidirect':177,850 'bloat':747 'boundari':1117 'br':318 'canon':137,363,372,379,389,402,569,575,593 'caus':144,433 'cctlds':1047 'cdn':697 'central':778 'check':110,193,1040 'choos':604 'chosen':974,981,986 'clarif':1111 'clear':1018,1084 'code':17,246,256,280,298,345,538,549,552,564,817,820,866,993,1057,1062 'common':13,262,327,488 'comparison':728 'complex':763 'con':733 'config':765 'configur':695 'confirm':846 'connect':1013 'consist':413 'consol':477 'content':625 'correct':20,89,1065,1069 'correspond':810 'countri':354,357 'creat':832 'criteria':1120 'critic':498,515,940 'cross':447,460,485,715,775 'cross-domain':446,459,484,714,774 'de':260,965 'declar':893 'default':68,205,229,526,531,691,855,959 'describ':1088 'design':208 'detect':12,791,935,1058 'differ':453 'dns':1011 'document':665 'domain':448,454,461,468,471,486,716,776 'e.g':257,309,455,539,553,999 'easi':741 'elsewher':381 'en':258,267,311,314,330,335,555,674,962 'en-gb':313,334 'en-uk':329,554 'en-us':310,673,961 'eng':264,540 'english':223 'entir':149 'entri':895,910 'environ':1100 'environment-specif':1099 'equival':808 'error':263,328,1005,1017 'es':347 'es-la':346 'everi':116,172,646,894 'exact':132,396,596 'example.com':456,668,677,684,881,884 'example.com/fr/page':676,883 'example.com/page':667,683,880 'example.de':458 'exist':84 'expert':1105 'failur':435,1012 'fallback':210,857 'fallback/selector':534 'file':663,758,923 'fix':492,995 'format':319,595 'found':938,1036 'fr':259,682,964 'full':200,914 'gb':315,336 'generat':11,19,50,88,724,788,830,864,875,966 'geo':623 'geo-target':622 'googl':145,475 'guess':1021 'han':291 'handl':1006 'hant':295 'hard':748 'header':79,104,657,754,869,976,979 'high':527,541,557,571,942 'hreflang':3,4,21,27,40,51,70,85,90,121,150,163,173,188,274,366,382,392,409,418,431,441,450,462,500,565,573,597,672,681,688,722,787,833,873,878,925,967,1034,1052,1070 'hreflang-sitemap.xml':982 'html':78,102,600,630,642,662,734,757,769,802,867,969,972,1000 'http':103,427,656,753,868,975 'http/https':429,578 'https':425,437,444,587 'i18n':28 'ignor':147,387 'imag':762 'implement':22,82,86,108,481,626,743,865,989,1053,1075 'includ':119,397,649,652,838,888,897,901 'inconsist':590 'incorrect':279,992 'indic':797 'input':1114 'instead':265,276,332 'intern':6,30,41,62 'internation':1043 'invalid':186,536,550,1055,1061 'iso':250,268,304,342,543,559,822,826 'issu':71,490,937 'ja':261,278 'japanes':282 'jp':275 'key':886 'la':348 'lang':803 'langua':39 'languag':34,64,95,195,219,242,245,321,324,360,537,612,712,792,796,816,899,933,950 'language-region':320 'language/region':16,638,1056 'languages/regions':214,813 'larg':610,705,772 'latin':349 'letter':255,548 'limit':1076 'link':158,167,631,666,735 'list':1059 'local':75 'low':603,617,946 'lowercas':323 'maintain':750 'mainten':786 'manag':779 'mani':711 'map':806 'match':133,395,517,592,809,1085 'medium':582,591,944 'mention':61 'mesh':201 'method':606,627,628,654,699,727,729,973,980,985,996,1054 'migrat':438,997 'mismatch':579 'miss':139,183,493,506,523,988,1122 'mistak':14,489 'mix':428 'move':572 'multi':33,36,94,98 'multi-languag':32,93 'multi-region':35,97 'multilingu':53 'multiregion':55 'must':118,131,166,175,234,248,368,394,420,648,896,905 'namespac':892 'need':616 'non':401,568,661,756 'non-canon':400,567 'non-html':660,755 'one':226,605 'option':300 'output':863,924,1094 'page':117,135,156,160,164,170,192,211,221,376,385,403,504,535,641,647,720,783,807,811,837,860,930 'path':799 'pdfs':664,761 'per':230,640,921 'permiss':1115 'place':643 'point':123,216,380,501,532 'prefer':608 'prefix':361 'process':789 'pros':732 'protocol':412,424 'provid':1067 'pt':317 'pt-br':316 'qualifi':286,302,620 'readi':1073 'recommend':482,703,987,1049 'ref':954 'refer':197 'referenc':114,129,142,496,841 'refus':1014 'region':37,99,285,297,301,322,326,358,551,614,619 'rel':378,670,679,686 'relationship':174,848 'replac':1066 'report':927,1015,1037 'requir':207,463,784,1113 'result':949 'return':153,184,237,464,507,518,844,955 'review':1106 'rule':698,887 'safeti':1116 'say':26 'scalabl':777 'scale':752,1004 'scan':793,931 'scenario':1007 'scope':1087 'search':476 'section':645,725 'see':721 'selector':220 'self':113,128,141,495,840,953 'self-ref':952 'self-referenc':112,127,140,494,839 'seo':2,7,29,31,42,63 'seo-hreflang':1 'separ':909 'server':694,764 'set':151,231,410,419,432,692,856,861,915,1072 'setup':487,717 'sever':491 'signal':189,1044 'site':56,100,611,635,706,709,738,773,794,1022 'sitemap':81,107,479,602,607,702,723,771,785,871,874,876,922,984,1002 'sitemap-bas':478 'skill':1079 'skill-seo-hreflang' 'slash':399,589 'small':737 'sourc':746 'source-sickn33' 'specif':356,1101 'split':916 'standard':583 'status':960 'stop':1107 'structur':1023 'subdirectori':1045 'subdomain':800,1046 'substitut':1097 'success':1119 'suggest':998,1024 'summari':928 'support':101,449 'tag':65,91,115,122,143,154,185,206,238,367,442,465,497,508,519,632,736,831,834,845,956,968,970,1035,1071 'target':624 'task':1083 'test':1103 'tld':801 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'total':929 'trail':398,588 'treat':1092 'tri':1031 'two':254,547 'two-lett':253,546 'typic':215 'uk':331,337,556 'unmatch':213 'unreach':1010 'updat':439 'uppercas':325 'url':130,138,364,373,390,393,415,505,570,576,581,585,594,798,920,951,1009,1029 'us':312,675,963 'use':23,45,46,57,72,249,288,303,355,421,542,558,1077 'user':25,60,1026 'valid':9,15,48,83,109,247,272,299,341,434,815,926,948,1102 'valu':977 'variant':639,713,740,934 'verifi':469,473,818,843,1027 'version':196,224,243 'via':693 'visibl':744,767,781 'without':284,359,613 'work':451,759 'x':67,204,228,525,530,690,854,941,943,945,947,958 'x-default':66,203,227,524,529,689,853,957 'xhtml':891 'xml':106,701,770,872,879 'xmlns':890 'xx':932,936,939 'zh':283,290,294 'zh-han':289 'zh-hant':293","prices":[{"id":"3d38c2b4-fb1e-4968-b581-bb9dd2891f12","listingId":"2448b567-e826-44ac-b3d6-ec425cc3e81f","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:44:32.384Z"}],"sources":[{"listingId":"2448b567-e826-44ac-b3d6-ec425cc3e81f","source":"github","sourceId":"sickn33/antigravity-awesome-skills/seo-hreflang","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/seo-hreflang","isPrimary":false,"firstSeenAt":"2026-04-18T21:44:32.384Z","lastSeenAt":"2026-04-22T12:51:44.273Z"}],"details":{"listingId":"2448b567-e826-44ac-b3d6-ec425cc3e81f","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"seo-hreflang","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34515,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-22T06:40:00Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"94bb357c43f50bf3effe38b1cbfa22eb1b881d8b","skill_md_path":"skills/seo-hreflang/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/seo-hreflang"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"seo-hreflang","description":"Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang implementations. Use when user says \"hreflang\", \"i18n SEO\", \"international SEO\", \"multi-language\", \"multi-region\", or \"language tags\"."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/seo-hreflang"},"updatedAt":"2026-04-22T12:51:44.273Z"}}