Skip to content

hreflang for a two-language site

The hreflang rules Google states, the mistakes that make the tags be ignored, and how this English and Ukrainian site marks its translated pages.

· Updated · 4 min read

Link tags with hreflang values en, uk and x-default for an English and Ukrainian page

hreflang tells Google that two pages are the same content in different languages, so each searcher gets the version that fits. The rules are strict: every version must list itself and all the others, every pair must point at each other, and the URLs must be fully qualified. If two pages do not link to each other, Google ignores the tags.

This site has an English version and a Ukrainian one, and it marks them with hreflang. Below are Google's rules, the tags I emit and the mistakes to avoid.

What Google says#

Google's guide to localized versions gives these rules:

  • Three equivalent methods. HTML tags in the head, HTTP headers, or an XML sitemap. Google calls them equivalent. It says using all three at once has no benefit in Search and may be harder to manage, and it suggests picking one.
  • List yourself too. "Each language version must list itself as well as all other language versions."
  • Return links. If page X links to page Y, page Y must link back to page X. If two pages do not point to each other, the tags are ignored.
  • Fully-qualified URLs, including https.
  • Codes. Only ISO 639-1 language codes and ISO 3166-1 Alpha 2 region codes are supported. You cannot give a country code by itself.
  • x-default. The reserved value x-default is for when no other language or region matches the user's browser. Google recommends it as a fallback, for example for a language selector page.
  • Language detection. Google does not use hreflang or the HTML lang attribute to detect the language of a page. The tags help it pick the right version for a user, not understand the text.

The page's HTML example, shortened, looks like this:

<link rel="alternate" hreflang="en-GB" href="https://en-gb.example.com/page.html" />
<link rel="alternate" hreflang="en-US" href="https://en-us.example.com/page.html" />
<link rel="alternate" hreflang="de" href="https://de.example.com/page.html" />
<link rel="alternate" hreflang="x-default" href="https://www.example.com/" />

Common mistakes#

  • Missing return links. First on Google's list of common mistakes, and the reason tags get ignored.
  • A region without a language. hreflang="GB" is not valid.
  • Reserved region codes. Google says that using EU, UN or UK in hreflang annotations has no effect on Google Search.

That last one is easy to confuse with the Ukrainian code. In hreflang, the language code for Ukrainian is uk. The region code for the United Kingdom would be GB, as in en-GB. So hreflang="uk" means Ukrainian, and it is right for a Ukrainian page.

What this site emits#

The Ukrainian pages live under /uk/ on the same domain. The examples below use example.com in place of the real domain. A page that exists in both languages gets three alternates in its head, in both versions:

<link rel="alternate" hreflang="en" href="https://example.com/about/" />
<link rel="alternate" hreflang="uk" href="https://example.com/uk/about/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/about/" />

The English page lists itself and the Ukrainian page, and the Ukrainian page lists the same set, which satisfies the self-reference and return-link rules. The x-default value points to the English page.

Only translated pages get these tags. The home page, About, Contact, Apps, the topic pages and the Lab examples are translated. The blog and the tools are English only, so they have no alternates, and the language switch on those pages takes the visitor to the Ukrainian home page. A tag that pointed to a page that does not exist would break the return-link rule, so a page is only marked once its translation exists.

The sitemap also lists the alternates for translated pages, with en, uk and x-default. That makes two of Google's three methods, tags and sitemap, which Google calls equivalent. Google says there is no benefit in using more than one and suggests picking one, so the sitemap copy is extra upkeep for me. Only indexable pages are in the sitemap, and About and Contact are noindex, so their alternates exist only in the HTML tags. A noindex page cannot be shown as an alternate in search, so those two tags do nothing there.

A checklist#

  1. Give every translated page the same set of alternates, including itself.
  2. Use https and full URLs.
  3. Check the codes: en, uk, de, en-GB, and never UK as a region.
  4. Add x-default for the version that should win when no language matches.
  5. Do not mark a page that has no translation.
  6. Check the result in the page source, not only in the code that generates it.

Limits of this post#

I read Google's guide on 18 October 2026. I have not looked at an international targeting report in Search Console for this site, so I cannot say how Google reads these tags in practice. The tools and the blog have no Ukrainian version yet.