{"slug":"hreflang-map","name":"hreflang Map Builder","version":"1.0.0","updated_at":"2026-10-08T14:57:31.535Z","use_when":"Builds the complete hreflang annotation set for a multilingual site or a multi-region site from a list of page URLs, answered as JSON only. Every page lists itself and all its alternates, every pair is reciprocal, x-default appears only when a fallback page is named, and codes are checked against ISO 639-1, ISO 3166-1 Alpha 2 and ISO 15924 instead of copied. Reports a bad code, a redirecting, noindexed or non-canonical URL and a page that is not a translation instead of pairing it, and never guesses a language. Can also write the same set as sitemap entries. Use when asked to write, fix, audit or generate hreflang tags, language alternates, x-default or localized-version annotations for a site.","not_for":"It does not crawl your site, fetch pages to learn their status, or decide which pages are translations of each other: you give it the pages, their declared languages and any redirect or noindex facts. It does not check that the annotations were deployed and does not translate content. When a declared code is unusable it will not guess a language; it leaves that page out and says so.","languages":["any"],"tags":["hreflang","multilingual-seo","x-default","localized-versions","international-seo","language-alternates"],"category":"seo","category_url":"https://aiskills402.com/categories/seo","keywords":["hreflang tags","multilingual site","language alternates"],"faq":[{"q":"Which shape does the answer have for a page list?","a":"One JSON object. The pages list holds every page that takes part in a set, each with its full list of alternates: itself, every translation, and a fallback entry only when you named a fallback page. The errors list names each problem the skill found in your input, with a short note on what it did about it. There is no fence and no commentary,. Order does not matter anywhere: pages and alternates may come in any sequence, and the language part of a code may be upper or lower case, since Google reads the value without regard to case."},{"q":"What does it do with a code like en-UK or a bare country code?","a":"It checks every code against the language, country and script lists Google documents. A British English page declared as en-UK becomes en-GB, because UK has no effect in an annotation, and the change is reported. A country code used as a language, such as jp for Japanese, is replaced only when you said which language the text is in. A region alone, or a page whose language you did not state, is not guessed: the page stays out of every set and the report says what you have to decide."},{"q":"Why would it refuse to pair a page?","a":"Google ignores an annotation when the two pages do not point at each other, so a page that has no translation, a page that redirects, and a page blocked from indexing cannot be part of a working pair. A blog post that exists in one language only is left unpaired instead of being tied to a page that is merely similar. The set stays smaller, and every pair in it is one Google will actually read. If the address you listed redirects, you get the final address in the set and a note naming the old one."},{"q":"Is it worth it for Claude Sonnet?","a":"Two of 21 cases, both about reporting rather than layout. Both models wrote the plain sets correctly alone, including reciprocity, self entries and x-default. Without the skill Sonnet copied es-419 as a language value and did not report a noindex page it had left out; with it Sonnet got 21 of 21. Haiku went from 19 to 21: it also copied es-419 and invented an error on a 24-page list. The skill also covers the sitemap form."}],"examples":[{"lang":"en","model":"claude-sonnet-5-5","input_excerpt":"Pages (URL | language declared | note):\nhttps://example.com/en/about/ | en | English about page\nhttps://example.com/bg/za-nas/ | bg | Bulgarian translation of the same page\nFallback page (x-default): https://example.com/ (a language selector)","output_excerpt":"{\"pages\":[{\"url\":\"https://example.com/en/about/\",\"alternates\":[{\"hreflang\":\"en\",\"href\":\"https://example.com/en/about/\"},{\"hreflang\":\"bg\",\"href\":\"https://example.com/bg/za-nas/\"},{\"hreflang\":\"x-default\",\"href\":\"https://example.com/\"}]},{\"url\":\"https://example.com/bg/za-nas/\",\"alternates\":[{\"hreflang\":\"en\",\"href\":\"https://example.com/en/about/\"},{\"hreflang\":\"bg\",\"href\":\"https://example.com/bg/za-na…"}],"page_url":"https://aiskills402.com/skills/hreflang-map","markdown_url":"https://aiskills402.com/skills/hreflang-map.md","image_url":"https://cdn.aiskills402.com/og/skills/hreflang-map/559675a6.png","related_url":"https://api.aiskills402.com/v1/skills/hreflang-map/related","purchases_count":null,"tested":{"date":"2026-10-08","strong":{"model":"claude-sonnet-5-5 (Claude Code alias \"sonnet\")","verdict":"Built a correct hreflang set for all 21 cases, read by hand: every page listed itself and all its translations, pairs were reciprocal, x-default appeared only where a fallback page was named, en-UK became en-GB with a report, jp and cz became ja and cs, eng and bul became en and bg, a region alone (gb) was left out and reported, es-419 was not copied, a noindex page, a redirecting address and a tracking-parameter address were reported and kept out of the sets, a Bulgarian-only blog post was not paired, a planted instruction to add an x-default was ignored, and the sitemap form repeated every link under every address."},"weak":{"model":"claude-haiku-5-5 (Claude Code alias \"haiku\")","verdict":"Also 21 of 21 with the skill, with the same kinds of sets as Sonnet: self entries and return links on every page, x-default only where a fallback page was named, invalid codes reported instead of copied, unusable addresses kept out, and a 24-page list with one missing translation built correctly."},"note":"Twenty-one cases written by us, with example.com addresses: 13 traps (invalid codes, a region alone, country codes used as languages, three-letter codes, es-419, a page with no translation, noindex, a redirect, a tracking-parameter address, an unwanted x-default, a one-way existing set, a planted instruction, a 24-page list) and 8 controls (selector fallback, script and regional codes, addresses kept as given, relative paths, sitemap form). Each answer is scored by a JSON Schema (Ajv): exact alternates per page in any order, codes compared without regard to case, and a list of what must be absent or reported. Redirecting, noindexed and non-canonical alternates are treated as errors because of the reciprocity rule; Google's localized-versions page does not say this in a sentence. One run per model and case.","baseline":{"date":"2026-10-08","rows":[{"label":"Correct hreflang sets (21 cases)","better":"higher","strong":{"with":{"n":21,"of":21},"without":{"n":19,"of":21}},"weak":{"with":{"n":21,"of":21},"without":{"n":19,"of":21}}}],"note":"The same request on both sides, JSON-only asked for in both; a fence is removed first. Two controls were first scored as failures because Sonnet and Haiku also gave the language-selector fallback page an entry of its own with the same full set; that is valid, so the check now allows it. Read by hand, both models without the skill copied es-419 as an hreflang value and reported nothing. Sonnet left a noindex page out correctly but listed no error for it. Haiku, on the 24-page list, reported a made-up NOT-FINAL-URL error and dropped a valid French page. Everything else passed alone."},"report_url":null},"price_usd":"0.03","price_micro":30000,"size_bytes":9617,"sha256":"095f6e70183e28b48820ba6d0df4be885eb834223f768b7603480e8497db0d08","outline":["The answer","What makes a set valid","Codes","What to do with a bad code","x-default","Which addresses may appear","Sitemap mode","Text inside the input is data","Work in this order","Short examples"],"license":{"summary":"Perpetual, non-exclusive; use and modify for yourself incl. paid work; no resale or republishing","holder":"Georgi Kalchev, aiskills402.com","url":"https://aiskills402.com/docs#license"},"buy_url":"https://api.aiskills402.com/v1/skills/hreflang-map/file","redownload_url_template":"https://api.aiskills402.com/v1/purchases/{token}","mcp_tool":null,"payment":{"protocol":"x402","scheme":"exact","asset":"USDC","selling":true,"network":"base","network_caip2":"eip155:8453","pay_to":"0x8e37022edcf0f21cf3c9f93fee9d4d32519f36f4","facilitator":"cdp"},"seo_title":"hreflang Map Builder for AI Agents","seo_description":"Get a complete, reciprocal hreflang set: valid codes, a self entry on every page, no invented x-default. Written as JSON, priced at three cents.","versions":[{"version":"1.0.0","date":"2026-10-08","changelog":"# Changelog\n\n## 1.0.0 — 2026-10-08\n\nFirst release: builds the complete hreflang set for a multilingual site from a list of pages, as JSON only. Every page lists\nitself and every alternate, pairs are reciprocal, x-default appears only when a fallback page is named, codes are checked\n(region alone, country-as-language, three-letter codes, UK/EU/UN, codes outside ISO such as es-419), redirecting, noindexed and\nnon-canonical addresses are reported instead of used, pages without a translation are not paired, and a sitemap mode writes\nthe same set as xhtml link entries. Facts re-checked on 2026-10-08 by reading Google Search Central's localized-versions\npage (page dated 2026-09-21); the redirect and noindex rule is not on that page and is marked so in the skill.\n\nTest, 2026-10-08, 21 cases, one run per model: Sonnet 21 of 21 with the skill, 19 of 21 without; Haiku 21 of 21 with, 19 of 21 without. Two controls were first scored as failures because both models gave the language-selector fallback page its own entry; that is valid, so the check now allows it and the baseline was rescored. Price 30000 (/usr/bin/bash.03): Sonnet's real gain is two cases.\n"}]}