Free SEO tool

Hreflang Generator and Checker

Build the hreflang tags for every language and country version of a page, then check a live set for the return links Google needs.

An hreflang generator writes the rel="alternate" hreflang tags that tell Google which version of a page to show in which country and language. This one validates every code against the ISO lists Google uses, writes all three formats Google accepts, and checks a pasted set for the missing return links that get the whole thing ignored.

It runs entirely in your browser. Nothing you paste is sent anywhere and there is no sign-up.

Build and check your hreflang tags

What is an hreflang generator?

An hreflang generator writes the block of <link rel="alternate" hreflang="..."> tags that goes in the head of every language or country version of a page, so you do not have to hand-type a line per version per page and get one of them wrong.

Most of them stop at the typing.

They will happily write en-UK, which Google's documentation says outright is not valid, or se for Swedish, which is actually Northern Sami.

They write the tags for one page and say nothing about the rule that every other page has to link back. That is the one that gets the whole set ignored.

This one checks the codes against the ISO lists Google reads, tells you what you probably meant, and has a second tab that takes a live set of tags, or a whole sitemap, and finds the missing return links.

Below the tool I cover how Google actually applies the rules, what hreflang does and does not do to your canonical tags, how to fix the "No self-referencing hreflang" warning your crawler keeps raising, the codes people get wrong, and why most Shopify stores should not be using a generator at all.

How this hreflang generator works

You add one row per version, give each a code and a URL, choose an x-default, and pick the format you need.

Three things happen behind that.

Every code is parsed the way Google parses it. Language first, from ISO 639-1. Then an optional script from ISO 15924, such as Hant. Then an optional country from ISO 3166-1 alpha-2.

Anything that does not fit gets a message that says what it is and what you probably meant.

Every version gets the same block. Google's rule is that "each language version must list itself as well as all other language versions", so the HTML output is one block you paste into every page in the set, and the sitemap output writes a <url> entry per version with the full list under each.

That is the part people skip.

A block that lists the other versions but not the page it sits on is the hreflang mistake I see most often.

It escapes what needs escaping. An ampersand in a URL becomes & in HTML and XML. The pasted-from-a-blog-post version never does that, and it breaks the sitemap silently.

How the rules are applied when Google reads your tags

Hreflang is all-or-nothing per pair of pages, and that is what makes it fragile.

Rule one: the set must be complete, including the page itself. Google: "each language version must list itself as well as all other language versions."

A page that lists French and German but not its own English URL has an incomplete set.

Rule two: every link must be returned. Google: "if two pages don't both point to each other, the tags will be ignored."

Page A saying "my French version is B" means nothing unless B also says "my English version is A".

This is why the checker asks for more than one page. One page cannot be validated on its own.

Rule three: URLs must be absolute. Google: "alternate URLs must be fully-qualified, including the transport method (http/https)."

A relative /fr/ is ignored. So is a URL that drops the protocol.

Rule four: the code is language first, country optional, never country alone. Google: "you can't specify the country code by itself." us on its own is not American English, it is nothing.

And the United Kingdom? GB, not UK. Google's documentation states that directly, because uk is the language code for Ukrainian.

x-default is the fallback, and it needs no language. Google: it "is used when no other language/region matches the user's browser setting". Point it at your main version or at a language chooser.

It is not required. However, Google recommends it, and every set I build has one.

Hreflang and canonical: which one wins?

They do different jobs, and they fight when you point them at each other.

A canonical tag says "this URL is a duplicate of that one, index that one instead." Hreflang says "this URL is a different-language version of that one, index both and show the right one."

Put a canonical from your French page to your English page and you have told Google the French page is a duplicate. It drops out of the index, and the hreflang on it is moot.

Google's rule is short. "If you're using hreflang elements, make sure to specify a canonical page in the same language, or the best possible substitute language if a canonical page doesn't exist for the same language."

So every version canonicals to itself, and hreflang connects them.

Two more things Google says on the same page. First, "for canonicalization purposes Google prefers URLs that are part of hreflang clusters", which is a good reason to keep your sets complete. Second, a rel="canonical" that carries an hreflang attribute is ignored for canonicalisation entirely.

However tempting it is to combine the two tags, they stay separate.

The checker flags a page whose canonical points at a URL listed under a different language code. That is the cross-language canonical, and after missing return links it is the fault I find most often on international sites. If the site is on Shopify, the same duplicate-URL problem shows up in other places too, and I go through them in Shopify duplicate content.

Fixing "No self-referencing hreflang"

If you run Ahrefs Site Audit, Screaming Frog or Sitebulb, you have seen this warning.

It means exactly what rule one above says: the page lists other versions but does not list itself.

The fix is one line per page.

Add the page's own URL to its own set, under its own code. The English page gets hreflang="en" pointing at the English URL, alongside the French and German lines it already had.

Paste the page into the checker above and it will tell you which code the self line is missing for.

However, the warning often points at a bigger problem. A page with no self-reference usually got its tags from a template that lists "the other languages", which means every page in the set is missing itself.

Fix the template once rather than the pages one at a time, and paste the whole set back in to confirm the return links survived. The crawl step in my technical SEO audit checklist is where this warning normally surfaces.

The related warning, "hreflang to non-canonical", is the cross-language canonical from the section above wearing a different name.

Hreflang codes people get wrong

Two-letter codes look interchangeable and they are not. The language list and the country list overlap, and where they overlap they mean different things.

• en-UK: not valid. Google's documentation says to use en-GB. On its own, uk is Ukrainian.
• en-EU: not valid. The EU is not a country in ISO 3166-1 and Google has no code for it. Use en for all English speakers or list the countries.
• se for Swedish: se is Northern Sami. Swedish is sv. Sweden the country is sv-SE.
• cz, dk, gr: those are countries. The languages are cs, da and el.
• jp, cn, kr: countries again. Japanese is ja, Chinese is zh, Korean is ko.
• tw for Taiwan: tw is Twi, a language of Ghana. Traditional Chinese for Taiwan is zh-Hant-TW or zh-TW.
• br for Brazil: br is Breton. Brazilian Portuguese is pt-BR.
• be for Belgium and ch for Switzerland: Belarusian and Chamorro. Belgium is nl-BE or fr-BE, Switzerland is de-CH, fr-CH or it-CH.
• es-419: 419 is a UN M.49 area code for Latin America, not an ISO 3166-1 country, and Google's documentation only lists ISO 3166-1. It is widely used and widely reported to work, but it is outside the format Google documents. The checker flags it as a warning, not an error.

Hreflang for Spanish: es, es-ES, es-MX and es-419

Spanish is the one that comes up most, so here it is in full.

es is Spanish anywhere. es-ES is Spain, es-MX Mexico, es-AR Argentina, es-US Spanish speakers in the United States. es-419 is the Latin America area code discussed above, useful but outside Google's documented format.

If you have one Spanish page for everyone, use es and stop there.

Hreflang examples you can load into the checker

Each of these is a set I have written for a client or found broken on an audit. Load one, break it, and watch what the checker says.

Hreflang on Shopify: check it, do not add it

If your store uses Shopify Markets with a subfolder, subdomain or domain per market, Shopify already writes the hreflang tags.

Shopify's documentation: "When you assign a domain, subfolder, or subdomain to a market with a specific language, the appropriate hreflang tags are added to every page on your store." It adds an x-default pointing at your primary domain, sets a self-referencing canonical on each version, and puts the same annotations in the sitemap.

So do not paste the output of this generator into a Markets store.

Shopify is explicit about why: "adding your own tags on top of the automatic ones can produce duplicate or conflicting annotations, which can hurt your store's search ranking."

What you want from this page is the checker. View source on a product page in each market, paste them in together, and confirm the set Shopify wrote is complete.

The exception is separate stores. Markets only knows about the markets inside one store, so if your countries run as separate Shopify stores, nothing connects them, and that is when you build the tags here and add them to each theme.

I cover the wider structure decision in Shopify international SEO, including why I would rather a store dominated one country than appeared in four. The Shopify SEO checklist has the rest of the launch list.

Which search engines read hreflang?

Google reads all three formats: the HTML tags, the HTTP header, and the sitemap. The HTTP header is the one for files that have no head, such as PDFs.

Yandex reads the HTML tags and states that it "no longer supports using the Sitemap file for language versions". If Russia matters to you, use the HTML format.

Bing is the odd one out.

Its Principal Program Manager, Fabrice Canel, said in 2020 that "hreflang is indeed a far weaker signal than content-language at Bing". The lang attribute on your <html> tag is the cheapest way to cover that, and the checker tells you when it disagrees with the page's own hreflang code.

What this tool will not do

Worth being straight about the limits before you rely on it.

• It does not fetch your pages. You paste the HTML or the sitemap. That means it can check a set before it is live, and it means it cannot crawl a site for you. For that, Ahrefs Site Audit and Screaming Frog both report hreflang issues, and the sections above tell you what each warning means.
• It cannot check a return link on a page you have not pasted. If page A lists page B and you only pasted A, the matrix marks B as unknown rather than guessing.
• It does not know what your pages say. Hreflang tells Google a page is French. It does not check that it is.
• It does not fix geotargeting. Hreflang is about which version to show, not about ranking in a country. Country targeting is a Search Console setting and a domain decision.
• It does not replace a plugin on WordPress. WPML, Polylang and TranslatePress write hreflang for you. Use the checker on their output rather than the generator on top of it.

Frequently asked questions

What is hreflang?

Hreflang is an attribute on a <link rel="alternate"> tag that tells search engines which language and, optionally, which country a page is for, and where the other versions live. Google uses it to show a French speaker in Canada the fr-CA version rather than the fr-FR one, and to stop the versions being treated as duplicates of each other.

Do I need hreflang if my site is in one language?

No. If you have one version of each page, there is nothing to point at, and adding a self-referencing tag alone does nothing. Hreflang earns its place when two or more versions of the same page exist in different languages or for different countries.

Is x-default required?

No, but Google recommends it and I always include one. It covers the visitor whose browser language matches none of your versions. Point it at your main version, or at a language chooser if you have one.

Can hreflang point to a different domain?

Yes. The only requirement is that the URL is fully qualified. example.co.uk and example.de can reference each other as long as both sides carry the tags. The return link rule applies across domains exactly as it does within one.

Does hreflang help rankings?

Not directly. It decides which of your versions is shown to which searcher, and it stops those versions competing with or duplicating each other. Google does not describe it as a ranking signal. Its value is that the right page appears in the right country, which is the thing that was going wrong before you added it.

Should hreflang go on every page or just the homepage?

Every page that has alternates, and each set is page to page. The English pricing page points at the French pricing page, not at the French homepage. A homepage-only set does nothing for the rest of the site.

Do hreflang codes need to be lower case?

No. The values are case insensitive. The convention this tool writes is lower case language, title case script and upper case country, as in zh-Hant-TW, because that is how the ISO lists are written and it is easier to read. zh-hant-tw means the same thing.

How many hreflang tags can a page have?

Google documents no limit. In practice the constraint is the sitemap, because every URL entry repeats the whole set: 40 versions of 10,000 pages is 400,000 alternate lines, and a sitemap file is capped at 50,000 URLs or 50 MB uncompressed. Split the sitemap by language when you get near that.

What about hreflang on WordPress?

The multilingual plugins write it for you. WPML, Polylang and TranslatePress all add the tags and, usually, the return links. The failure I see is a plugin that lists the other languages and forgets the self-reference. Paste one page from each language into the checker and it will tell you in one go.

Does Bing use hreflang?

Weakly. Bing's Fabrice Canel said in 2020 that hreflang "is indeed a far weaker signal than content-language at Bing". Set the lang attribute on the <html> tag of each version and you have covered it.

Built by Graeme Whiles, an SEO and AEO consultant. Every rule on this page is quoted from Google's, Shopify's or Yandex's own documentation, and the code lists are generated from the ISO standards. Last checked 14 September 2026.