Hreflang tells a search engine which URL to show a searcher based on their language and location, for example sending a French speaking visitor in Canada to a fr-CA version of a page instead of the default English one, when both exist. It is one of the more error prone tags in common use, because every version of a page needs to reference every other version, including itself, and a single missing return tag can quietly break the whole cluster.
Every code and every URL you enter stays in your browser while the tool validates and assembles it, so drafting hreflang for a set of pages that has not launched yet never depends on a server call. The output is a complete set of hreflang link tags or, if your site is better served by headers or a sitemap, the same data in either of those forms instead.
Language codes, region codes and the difference between them
An hreflang value is a language code, optionally followed by a hyphen and a region code. The language code follows ISO 639-1, the two letter standard, so English is en and Spanish is es. The region code follows ISO 3166-1 alpha-2, so United States is US and Mexico is MX, and it narrows the language to a specific locale, meaning es-MX targets Spanish speakers in Mexico specifically, distinct from es-ES for Spanish speakers in Spain.
A common mistake is swapping the two, writing something like US-en instead of en-US, or using a three letter code from a different standard entirely. This tool validates each part of every pair against the real iso 639-1 language codes and ISO 3166-1 region list and flags anything that does not match, before it becomes a tag that a search engine silently ignores because it does not recognise the code.
Every page needs to reference every other page, including itself
Hreflang is not a one way pointer from a default page to its translations. Every URL in the cluster needs a complete set of hreflang tags listing every other language and region version, and critically, a self referencing tag pointing at itself with its own code. Skipping the self reference is one of the most common hreflang errors, and it can cause the whole set of tags to be ignored rather than partially applied.
This generator handles that automatically. Add each URL with its language and region pair once, and the tool builds the full matrix, meaning every page's output includes a reference to every page you entered, itself included, without you needing to copy the same block with small variations across each version by hand.
x-default hreflang, and when you actually need it
x-default marks the page a search engine should show when none of the defined language and region pairs match a visitor, most commonly a language selection page or a version aimed at a general international audience rather than one specific locale. It is optional, but its absence is not an error, it simply means there is no explicit fallback and a search engine will make its own choice among the versions you have listed.
Set x-default hreflang on a genuine fallback page, not on one of your regular language versions arbitrarily. Pointing x-default at, say, your English United States page implies that page is the intended experience for a visitor whose language does not match anything else in the set, which may not be true for a visitor from, for example, Japan or Brazil where a language selector would serve them better.
Three ways to implement hreflang, and how this tool outputs all of them
Link tags in the HTML head are the most common implementation, one line per language and region pair placed on every page in the cluster. HTTP headers achieve the same result without touching the page's markup at all, which is the only option for a non HTML resource such as a PDF, since there is no head element to place a tag in. Sitemap XML entries bundle the hreflang information into the sitemap itself using an extension to the standard sitemap schema, which keeps every page's markup untouched and centralises the whole cluster in one file.
This tool generates all three formats from the same input, so switching between an HTML based implementation and a sitemap based one does not mean re-entering your language and region pairs a second time. Whichever format you choose, the underlying multilingual seo tags describe exactly the same relationships between your pages.
How this hreflang tag generator validates your codes
Every language code you enter is checked against the actual ISO 639-1 list of two letter codes, and every region code against the ISO 3166-1 alpha-2 list of two letter country codes, rather than a loose pattern match that would accept a plausible looking but nonexistent combination. A code that fails validation is flagged clearly before it reaches the generated output, since a search engine encountering an invalid code typically ignores that specific tag rather than raising any visible warning of its own.
The generator also checks that every URL in the set appears in every other URL's output, catching the missing return reference error before it ships, which is the single most common reason a correctly coded hreflang cluster still fails to work as intended.
| Format | Best for |
|---|---|
| Link tags | Standard HTML pages, most common choice |
| HTTP headers | Non HTML resources such as PDFs |
| Sitemap XML | Large sites, keeps page markup untouched |
How to use the hreflang tag generator
- 1
Add each language or region version
Enter the URL and the language and region pair for every version of the page, including the default.
- 2
Set x-default if you have a genuine fallback
Mark one URL as x-default only if it is a real fallback, such as a language selector, not just your main locale.
- 3
Fix any flagged codes
Review validation messages for any language or region code that does not match ISO 639-1 or ISO 3166-1.
- 4
Choose an output format and copy
Pick link tags, HTTP headers or sitemap XML depending on your setup, then copy the hreflang tag generator output for each page.
Related tools worth bookmarking
Sources and further reading
- Google Search Central: Localized versions of your pagesGoogle's own documentation of how hreflang works, including the self reference requirement and x-default handling.developers.google.com
- ISO: Language codes, ISO 639The primary standards body source for the ISO 639-1 two letter language codes this generator validates against.iso.org
- RFC 5646: Tags for Identifying LanguagesThe internet standard defining how language and region subtags combine, which underlies the hreflang attribute's syntax.rfc-editor.org
Frequently asked questions
Common questions about the hreflang tag generator.
Writing hreflang tags by hand means every page in the cluster needs the full list of every other page's URL and code repeated correctly, and a single typo or missing return reference on one page can silently break the whole set. A hreflang tag generator builds that full matrix from one shared list, which removes the copy paste errors that make hand written hreflang unreliable on anything beyond two or three pages.
Language first, then region, separated by a hyphen, for example en-GB for English in the United Kingdom. The language code follows ISO 639-1 and the region code follows ISO 3166-1 alpha-2. Reversing the order or mixing in a different code standard is a common mistake that causes a search engine to silently ignore the tag.
A language code alone, such as just en, is valid and targets every English speaker regardless of location. Add a region code specifically when the content actually differs by locale, for example different pricing or spelling between en-US and en-GB. Adding a region code without a real content difference adds complexity without a corresponding benefit.
Missing the self reference, where a page fails to list itself among its own hreflang tags, is one of the most common hreflang errors and can cause the entire set of tags on that page to be disregarded rather than just the missing one. Every page in the cluster needs a complete set of tags including a tag pointing at its own URL and code.
Use it on a genuine fallback page, most often a language selection page or a general international version, meant for a visitor whose language does not match any of your defined pairs. Do not set it on one of your regular locale specific pages just because it is your primary market, since that implies it is the intended experience for every unmatched visitor globally.
Yes. Hreflang works with any URL structure, whether the different versions live on separate domains, separate subdomains, separate subfolders or even the same URL with different query parameters. What matters is that each distinct version has its own reachable URL and that every version's hreflang tags correctly reference every other version's actual URL.
Any of the three works, and they are not mutually exclusive, though mixing methods for the same page risks conflicting signals if they fall out of sync. HTML link tags are simplest for a typical page. HTTP headers are required for non HTML resources like PDFs. Sitemap XML entries are convenient for a large site, since they centralise the whole cluster in one file instead of editing every page's markup.