SEO & Marketing

hreflang: A Flawless Implementation Guide for Multilingual Sites

If Search Console is throwing "no return tags" or "missing x-default" errors for hreflang, this guide shows exactly those cases with code samples and testing methods.

SEO & Marketing

In the "International Targeting" report in Search Console, under the Language section, there's a red error you can't get rid of: Missing return tags for the English version, and Missing x-default value for the Persian version. Your site has three languages, each page points to the others with hreflang, but Google hasn't accepted half of these references. The problem is usually not in the tag; it's in its asymmetry.

hreflang is a signal, not a command. Google uses it to show the correct version in search results for each language and to set the others aside as duplicates. If this signal is contradictory, Google prefers to ignore it and decide for itself. You see the result in Search Console: the English version appears in Persian results, or none of the versions takes its proper place.

The first rule of hreflang: the reference must be bidirectional

Every page that points to another page with hreflang must receive a return reference from that same page. If example.com/fa/ says "my English version is example.com/en/", that English page must also point to exactly that Persian URL. One-sidedness is the most common cause of the Missing return tags error.

This error occurs when, for example, you added the Persian page later and didn't update the tags on the English page. Or worse: on the English page you used a URL with www and on the Persian page without it. From Google's perspective these are two different URLs, even if both reach the same server.

The practical rule is simple: every URL in the hreflang set must be exactly the same string that appears in that page's canonical tag. If your canonical is https://example.com/fa/, the hreflang tag must be the same, with the trailing slash and without extra parameters.

A correct example of tags in the head

For a site with three languages — Persian, English, and Arabic — the following block must be repeated in the head of all three pages, with the only difference being that each page also points to itself:

<link rel="alternate" hreflang="fa-IR" href="https://example.com/fa/" />
<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="ar" href="https://example.com/ar/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/" />

Three points are hidden in these four lines. First, self-reference (fa-IR on the Persian page) is mandatory; omitting it causes Google to drop that page from the set. Second, the language code must conform to ISO 639-1, and if the region matters it should be combined with ISO 3166-1-alpha-2: fa-IR is correct, fa_IR with an underscore is wrong, and persian is completely meaningless. Third, x-default is the version shown to a user whose language doesn't match any of the versions.

Where to put x-default

Choosing x-default is a business decision, not a technical one. If your main audience is international, the English version makes sense. If it's an Iranian e-commerce site and most traffic from outside Iran is low, putting the Persian version on x-default isn't wrong, but it means a German user also sees the Persian page. In most cases I choose English, unless the product has no English version at all.

A point that's less often mentioned: x-default must be present on all pages in the set, not just the homepage. If on a product page you've only placed the fa and en tags and left out x-default, the same Missing x-default value error comes back.

Three implementation methods and my choice

There are three ways to declare hreflang, and choosing between them depends on the site architecture, not on preference.

MethodAdvantageCost and limitation
link tag in headSimple, testable with curl, no delayIncreases head size; on a site with ten languages, each page has ten extra lines
HTTP headerWorks for PDF and non-HTML filesOnly for non-HTML resources; ignored in HTML
XML sitemapCentralized management, suitable for large sitesDelay in application; requires regular sitemap regeneration

For sites up to a few thousand pages, I choose the tag in the head. The reason is testability: with a curl -s https://example.com/fa/ | grep hreflang you see what's being served, without waiting for the next crawl. For a marketplace with a hundred thousand pages and ten languages, the sitemap is more logical, because keeping ten tags in the head of each page both increases HTML size and the likelihood of inconsistency.

One warning: if you've placed tags both in the head and in the sitemap, both must describe exactly the same set. A contradiction between the two is an error that's hard to trace in reports.

Here's where they go wrong: hreflang on a noindex page

The error I've seen most often and that isn't always clear in the Search Console report: the development team publishes the English version with <meta name="robots" content="noindex"> because "the content isn't complete yet." Then hreflang points to it. Google removes the noindex page from the index and as a result sees the entire hreflang set as incomplete. The sign is this: the Persian version appears in English results, or no version ranks for an English query, while all the tags appear correct.

The same thing happens with Disallow in robots.txt, with a worse difference: Google doesn't read the page at all, so it doesn't see the hreflang tags inside it either, and the return reference is never recorded. If a page is in the hreflang set, it must be crawlable and indexable. There's no other way.

How to find errors before Search Console

Don't wait for Google's report; its cycle can take several weeks. A small script acts faster. For example, to check that each page actually returns a 200 code and serves the tags:

for u in fa en ar; do
  echo "== $u =="
  curl -sI "https://example.com/$u/" | head -n 1
  curl -s "https://example.com/$u/" | grep -o 'hreflang="[^"]*"'
done

If in the output the status code is anything other than 200 or the tags are incomplete, you've found the problem right there. To check redirects, also run curl -sIL and make sure the chain has no more than one hop; a 301 redirect from the version without a slash to the one with a slash, if not accounted for in the hreflang tag, breaks the reference.

For a technical check of the domain and DNS and to make sure the language versions resolve on the same domain without issues, the domain and DNS lookup tool speeds things up. If you're redesigning the site structure, make the decision about the URL pattern (subdirectory vs. subdomain) before launch; changing it later means rewriting all the tags. ServerNet's web design services usually come in at this stage.

Subdirectory or subdomain?

For a multilingual site, I choose the subdirectory (example.com/fa/). Domain authority is consolidated in one place, SSL and CDN management is simpler, and reporting in Search Console requires one property instead of three. The subdomain (fa.example.com) only makes sense when the versions are truly independent: a separate content team, a separate server, or a different brand. Otherwise, you pay its maintenance cost without gaining anything.

Common mistakes I see in reports

  • Wrong language code: using en-US for content whose audience is global. If the English version is for all countries, just write en.
  • Pointing to a page that redirects: the tag points to http:// and the server redirects to https://. Google sees this as a reference to a different page.
  • Machine translation without review: hreflang can't rescue low-quality content. If the Arabic version is raw machine translation, it's better to have no hreflang at all than to send the user to a page they immediately bounce from.
  • Forgetting paginated pages: page 2 of the product list also needs its own hreflang set, otherwise the language versions of that page compete with each other.

One point about measurement: after fixing the tags, look at the effect in real user data, not just in the coverage report. I've explained the method in measuring real user performance with CrUX. If after changing the language structure the TTFB of the new versions went up, read the difference between TTFB and load time; it usually has nothing to do with hreflang and the problem is elsewhere.

Finally, if you want to make sure everything looks right from a crawler's perspective, SEO and webmaster tools are a good starting point. And if you'd prefer to hand this whole process to another team, ServerNet's SEO services include hreflang implementation and review as well.

Frequently asked questions

Can hreflang improve a site's ranking in Google?

hreflang doesn't improve ranking by itself. What it does is prevent language versions from competing with each other and show the right version to the right user. If the Persian and English versions both appear for a single query and one pushes out the other, correct hreflang solves this problem.

What's the difference between hreflang and canonical?

canonical says "which version is the primary one for this content" and is used for duplicate pages in the same language. hreflang says "these are language versions of one content and each is primary for its own audience." The two don't contradict each other: each page should have a canonical to itself and hreflang to the other versions.

Why does Search Console give a "no return tags" error when I've placed the tags?

Almost always because of URL inconsistency: a difference between http and https, the presence or absence of www, a trailing slash, or a UTM parameter in one of the versions. Google sees these as different URLs. Compare each URL in the hreflang set with that page's canonical and make the strings exactly identical.

Should I put hreflang on every page or just the homepage?

On every page that has a language version. Placing hreflang only on the homepage and not on product or article pages is one of the most common reasons the set remains incomplete. If a page has no translated version, it doesn't need hreflang at all.

ServerNet Support

ServerNet engineering & editorial team — specialists in infrastructure, networking and web hosting.

SEO Services
Share:

Comments 0

No comments yet — be the first!

Leave a comment

Related service

SEO Services

SEO is not a cost, it's an investment. With technical SEO, content strategy and principled link building, ServerNet raises your ranking on Google and builds real, lasting organic traffic.