Hreflang Tag Generator

What is an hreflang generator, and what code does it give you?

An hreflang generator writes the code that tells Google about the language and region versions of one page. You never type it by hand. You enter each version's URL, language and, if needed, country once. The tool then turns that into one of three formats: HTML link tags for the page head, xhtml:link entries for an XML sitemap, or an HTTP Link header for files such as PDFs.

I open this tool in two situations above all. First, when we add a language to a client's site; second, when an audit shows the wrong language version ranking. The tag itself is simple. However, with five languages and an x-default the number of lines grows fast, and a single wrong code can void the whole set. If you want the fundamentals first, read my guide on what the hreflang tag is and how to use it. This page, in contrast, focuses on the code the tool produces and how you put it on your site.

• Code assembly: it merges language and region into a single value such as en-GB.
• Reciprocal set: every version lists all versions, itself included.
• Checks: it flags duplicate codes, a missing https prefix, relative URLs and a missing x-default line.
• Try an example: it loads this page's own Turkish, English and German set.

HTML, XML sitemap or HTTP header: which method should you choose?

According to Google's documentation on localized versions, the three methods are equivalent for Search, so you pick whichever suits your site. Using all three at once brings no extra benefit in Search. Moreover, debugging gets harder when the values disagree, so I choose one method per project and document it.

• HTML link tags: the easiest route if you can edit the page template. You paste the same block into the head of every page in the list; this site uses that method too.
• XML Sitemap: sensible for large page counts, or when a hosted platform keeps you out of the head. The annotations live in the sitemap rather than in the page source. You can also move the entries into a sitemap you built with the XML sitemap generator.
• HTTP header: the method meant for non-HTML files such as PDFs, because those files have no head. You add the value as a Link header to that file's response in your server configuration.

To decide, ask one question: where does the most reliable list of your language versions live? If the template knows it, HTML usually causes fewer errors; if a product database knows it, the sitemap route usually does.

How do you add the hreflang generator output to your site?

Where the copied code goes depends on the format you picked. One rule applies to every format: each page in the set must carry the same list. That is why the tool produces a single block, and you place that block on every version unchanged.

1. HTML: paste the block into the head of every version, ideally next to the canonical tag. Google requires the link tags to sit inside a well formed head section, so a line that ends up in the body may not count.
2. XML Sitemap: move the url entries into your sitemap and check that the urlset element declares the xhtml namespace. Then submit the sitemap in Search Console.
3. HTTP header: the Copy button returns the value as one line. Add that line to the file's response on your server, then confirm the header in the Network tab of your browser's developer tools.

On platforms such as WordPress or Shopify, multilingual plugins and features often generate hreflang tags on their own. So search the page source for hreflang before you add anything; two sets with conflicting values create a new problem instead of solving one. In our SEO consulting audits, this double set is one of the issues we see often.

What do the warnings in the Checks list mean?

The Checks list next to the code exists so you catch the most common errors before you copy. The badge above the code shows Ready for a clean set, Suggestions when there are only tips, and Errors when something needs fixing.

• Reciprocity, self reference: always shows Automatic, because the tool builds one complete list. To meet the rule, you only need to place the same block on every version.
• Language and region codes: reports a Duplicate error if you chose the same language and region in two rows. When two different URLs carry the same code, it becomes unclear which one belongs to that audience.
• Absolute URLs (https): adds https:// when you leave it out and tells you so. Relative URLs starting with / and URLs without a domain count as errors, since Google wants alternate URLs fully qualified, protocol included.
• The x-default row: shows Missing, recommended when the field is empty. Google recommends the value for visitors who match no version, but it does not require it.
• Language catch-all: suggests a fix when you have regional versions such as en-GB and en-US but no plain en. Google advises sites that serve one language to several countries to add a catch-all URL for users of that language in other places.

When should you add a region code?

My short answer: only when the content really changes by country. Different prices and currencies, shipping terms, legal texts or local phone numbers justify a regional version. Say you have one German page, and visitors in Germany, Austria and Switzerland all see the same text. Then a plain de value is enough and more robust.

In the tool, a regional setup works like this: you choose the same language in several rows and give each row a different country. For example, three rows for de-DE, de-AT and de-CH, then one de row without a region. If you skip that last row, the Language catch-all item in the Checks list reminds you.

• The language code always comes first; you cannot use a region code on its own.
• For the United Kingdom choose GB, not UK; picking from the list prevents that mistake.
• If the script matters in Chinese, choose zh-Hans or zh-Hant and add a country when needed.

As the number of markets grows, these choices also shape your content strategy. For the architecture and content planning side, see my multilingual website SEO guide.

How do you test the set you built with the hreflang generator?

After the code goes live, I check it in this order.

1. Open the source: view the page source of each version and search for hreflang. The number of lines and the values should match on every version.
2. Check status codes: every URL in the set should return 200 directly. If one redirects, trace the chain with the redirect checker and put the final URL into the set.
3. Look at the canonical tag: every version should name its own URL as canonical. If one lacks it, the meta tag generator also writes the canonical line.
4. See what Google sees: in the URL Inspection tool in Search Console, check which canonical URL Google chose for the page.

One more note: the International Targeting report in Search Console no longer exists. Google removed the report but states clearly on its help page that it still supports hreflang. So instead of the report step in older guides, use the manual checklist above.

Should you build hreflang sets by hand on large sites?

No; the tool is ideal for setting up the pattern and verifying a few pages, not for entering thousands of pages one by one. On a large site I use the output as a template. I build one page's correct set here, then move the same structure into the CMS template or the sitemap code.

With the sitemap method, also plan for size. Sample calculation: 1,000 pages in 4 language versions means 4,000 url entries. If x-default points to one of those versions, each entry holds 5 xhtml:link lines, so 20,000 lines in total. Google limits a single sitemap to 50,000 URLs or 50 MB uncompressed; above that, you split the sitemap and submit a sitemap index file.

As languages and markets multiply, the work shifts from a technical tag to a strategy question. I explain when outside help makes sense in who needs international SEO and GEO consulting.