What hreflang tags do
When the same page exists in several languages, or in one language for several countries, hreflang tells search engines that these URLs belong together and which audience each one is for. Google then shows a searcher the version that fits their language and region, for example the en-GB page with prices in pounds to someone in Britain and the en-US page to someone in the States. This is a core part of international SEO.
Google's documentation, Tell Google about localized versions of your page, recommends hreflang when you translate only the template of a page, when you have small regional variations of the same content, and when you translate the whole site. Localized versions count as duplicates only if the main content stays untranslated. hreflang does not tell Google what language a page is in: Google says it detects the language with its own algorithms and does not use hreflang or the HTML lang attribute for that.
Language and country codes
Each hreflang value starts with a language code from ISO 639-1, the two-letter list, optionally followed by a hyphen and a region code from ISO 3166-1 alpha-2. Google accepts the codes in any case, but writing the region in capitals, as in en-GB, follows the ISO convention. This generator checks every code against the IANA language subtag registry, which contains these ISO lists, and shows the name of each language and country so typos stand out.
| Value | Means | Valid |
|---|---|---|
| de | German, any country | Yes |
| en-GB | English for the United Kingdom | Yes |
| zh-Hant-TW | Chinese in Traditional script for Taiwan | Yes |
| en-UK | UK is a reserved code, use GB | No |
| be | Belarusian, not Belgium | Yes, but often a mistake |
| es-419 | Spanish for Latin America, an area code | Not supported by Google |
| en_US | Underscore instead of a hyphen | No |
A country code on its own is never valid, because the first part is always read as a language. Google also supports a script code from ISO 15924, such as zh-Hant for Traditional Chinese or zh-Hans for Simplified Chinese, optionally with a region, as in zh-Hans-US. Codes outside these lists are not supported, and Google gives es-419 as an example. Reserved region codes such as EU, UN and UK have no effect in Google Search.
Return links: every page must link back
hreflang only works when the pages confirm each other. If the German page lists the British page as an alternate, the British page has to list the German page as well. Google ignores links that are not confirmed both ways, so that another site cannot simply name itself as an alternate version of yours. Missing return links are the first item on Google's list of common mistakes.
The rule that follows from this is simple: each version lists itself and all other versions, and the block is identical on every page. That is why this generator produces one block for all versions instead of one per page. When a complete set is hard to maintain on a large site, Google allows you to leave out some languages on some pages and still processes the pairs that do point to each other. In that case, link new language versions both ways with your original, strongest version first.
To audit pages that already have tags, open "Check existing hreflang tags" in the tool. For HTML or a header, add the URL of the page, and the checker tells you if the page forgets to list itself. For a sitemap, it compares all entries with each other and reports every missing return link.
HTML, sitemap or HTTP header
Google accepts hreflang in three places and treats them as equivalent. Choose the one that is easiest for your site; using more than one brings no benefit in Search and makes mistakes more likely.
- HTML link tags go in the head of every version. Each tag needs rel="alternate", the hreflang value and the full URL. Do not put other alternate attributes such as media into the same tag. The Meta Tag Generator covers the other tags in the head.
- The XML sitemap lists each URL in its own url element, with an xhtml:link child for every version including itself, and declares the xhtml namespace on the urlset element: xmlns:xhtml="http://www.w3.org/1999/xhtml". The xhtml:link elements do not count toward the URL limit of a sitemap. A sitemap can only contain URLs in its own folder or below it. For a plain list of URLs without alternates, use the XML Sitemap Generator.
- The HTTP Link header carries the same set in the response headers, which is the way to annotate files that have no HTML head, like PDFs. The header lists every version, including the requested one, and is identical for each of them.
Full URLs, x-default and a catchall page
Every URL must be fully qualified, with https:// or http:// in front. A path like /de/ or a protocol-relative address like //example.com/de/ is not enough. The versions may live on different domains, such as example.de and example.co.uk. If you moved some versions to new URLs, make sure the hreflang tags point to the final addresses, not to old ones that redirect; the Redirect Generator helps you set up those moves.
The value x-default names the page for everyone whose language and region match none of your versions. It needs no language code, and Google says it was designed for language selector pages. If you have several regional versions of one language, Google also suggests a generic version for speakers of that language elsewhere: next to en-IE, en-CA and en-AU, add an en page, which can simply be one of the regional ones. The checker reminds you when that catchall is missing.
How to use the hreflang tag generator
- 1Add one row per version: the language code, optionally with a country, and the full URL of that version. The name under each code confirms what it means.
- 2Add an x-default URL if you have a language selector or a page for everyone else, and fix anything the checks mark as an error.
- 3Choose HTML, Sitemap or HTTP header, copy the code, and put the same block on every version, or upload the sitemap and submit it in Google Search Console.
Frequently asked questions
Does every page need to link back?
Yes. If page A names page B as an alternate, page B has to name page A too. Google ignores hreflang links that are not confirmed in both directions, so nobody can declare your pages as alternates of theirs. The easiest way is to put the same complete block, including the page itself, on every version.
Is it en-UK or en-GB?
en-GB. The region part uses ISO 3166-1 alpha-2 country codes, and the code for the United Kingdom is GB. UK is a reserved code, and Google says reserved codes such as UK, EU and UN have no effect in Google Search. The checker flags en-UK and offers the fix.
Can I use a country code without a language?
No. The first part is always the language. hreflang="de" means German, but hreflang="be" means Belarusian, not Belgium. For Dutch speakers in Belgium you write nl-BE, for French speakers fr-BE.
Do I need x-default?
It is optional but useful. x-default names the page for visitors whose language matches none of your versions. Google says it was designed for language selector pages and works best there, though you can use it on any page.
Should I use HTML tags, the sitemap or HTTP headers?
Pick one. Google treats the three methods as equivalent, and using several gives no benefit in Search but more to maintain. HTML tags are simplest for a few pages, a sitemap scales better for large sites, and the Link header is the only option for files like PDFs.
Does hreflang tell Google what language my page is in?
No. Google says it does not use hreflang or the HTML lang attribute to detect the language of a page; it works that out from the content. hreflang tells Google which pages are versions of each other, so it can show the right one to each searcher.