Most generators emit whatever you type into them. This one checks the codes first — against the full ISO 639-1 and ISO 3166-1 lists — and tells you when a perfectly valid code is not the one you meant.
One row per language or country version. The self-referencing tags are added for you — they are the part people leave out.
Against the whole of ISO 639-1 and ISO 3166-1, not a shortlist of the popular twenty.
Pick one method. Two is worse than one, because the two drift apart.
Worth reading before you paste the output anywhere.
If page A declares page B as an alternate and page B does not declare page A back, search engines throw the pair away. Not one tag — the pair. There is no error, no warning, and nothing in any report to show it happened.
That is why this tool outputs one identical block for every URL in the set rather than a different block per page. Paste the same thing everywhere and the return tags cannot be wrong.
An hreflang annotation tells a search engine that two or more URLs are the same page written for different languages or countries, so the right version is served to the right person. It is worth being precise about the limits, because most of the disappointment around hreflang comes from expecting more:
Three places are valid, and you should use exactly one of them:
Link header. For files that have no head to put tags in — PDFs, images, feeds. Same content, delivered as a response header.Doing two of them is a common and avoidable mess. The head tags get updated during a redesign, the sitemap does not, and now the same URL is declared two different ways by two teams who have never spoken to each other.
Syntax checkers pass all of these. They are wrong anyway, and they are the reason this tool carries the whole ISO list rather than a regular expression:
| Written | What it actually means | What was meant |
|---|---|---|
| en-UK | Not valid — UK is only reserved in ISO 3166-1 | en-GB |
| uk | Ukrainian | en-GB |
| eu | Basque | Europe — which hreflang cannot target at all |
| es-LA | Spanish in Laos | Latin America — use es, or the countries one by one |
| es-419 | Not valid — 419 is a UN M.49 code, not ISO 3166-1 | as above |
| ar-ME | Arabic in Montenegro | the Middle East — again, not a thing hreflang has |
| en_US | Not valid — the separator is a hyphen | en-US |
| US | Not valid — a country cannot stand alone | en-US |
| iw | Retired code for Hebrew | he |
The pattern is that hreflang has no concept of a continent, a region or a trading bloc. There is a language and, optionally, a country. Everything on that list is somebody trying to express something the format simply does not have, and getting a valid code that means somewhere else.
es serving all of Latin America beats es-MX, es-AR and es-CO pointing at three near-identical pages that then compete with each other.It generates and it validates codes. It does not crawl your site, so it cannot see whether the tags you paste actually ended up on every page or whether the return tags reciprocate in production. That is a different job, and it is the one worth doing after deployment — my international SEO audit checklist covers how I go through it, and the Spanish guide to hreflang works through the return-tag failure in detail.
One more thing, since it illustrates the point: this page is paired with a Spanish version, and both sides declare each other. You can read the whole pair out of this page’s own <head> — three tags, en, es and x-default, byte-identical on both URLs. That is the entire rule, applied to the page you are reading.
Link HTTP response header, or xhtml:link elements in an XML sitemap. The head is usual; the header exists for files with no head, like PDFs; the sitemap is easier to maintain at many locales. Using two at once is how contradictory declarations appear.en-GB. UK is only reserved in the standard, and an annotation using it is ignored. It is the most common single error in hreflang, and nothing in a browser or CMS warns you.