Hreflang explained, with examples for multilingual websites

Hreflang is an annotation that tells Google "these URLs are the same page in different languages or for different regions", so it can show each searcher the version in their language. Every version lists every version, including itself. The links must be confirmed in both directions, or Google ignores them. An x-default entry names the page for everyone whose language you do not cover. Hreflang does not raise rankings and does not translate anything; it decides which of your existing pages appears.

It is the search half of a multilingual site, set up alongside separate URLs per language and translated metadata, as described in our guide to building an Arabic website. We set it up on every Arabic and multilingual website we build. Everything below follows Google's own documentation on localized versions of a page.

What problem does hreflang solve?

Without it, Google has to work out on its own that example.com/services/ and example.com/ar/services/ are the same page. It often manages, but not always. The usual symptoms are an English page appearing for Arabic searches, or a UAE page and a Saudi page in the same language competing for one query.

Google recommends declaring alternates in three situations: the content is fully translated; only the template (menus, footer) is translated while the main content stays in one language, as on many forums; or the content is in one language with small regional differences, such as prices in AED and SAR.

Hreflang does not do several things people expect of it:

• It does not set the page's language. Google detects language from the visible content. It does not use hreflang or the html lang attribute for that.
• It does not fix duplicate content. Translated pages are not duplicates. Google's documentation says localized versions are only treated as duplicates if the main content stays untranslated.
• It does not need to stay on one domain. Alternates can sit on different domains, such as example.ae and example.sa.

How do you write hreflang tags for an English and Arabic site?

Put this block in the head of both the English and the Arabic page:

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

The block is identical on both pages. That is the rule people break most: each page lists itself as well as the others. The other rules from Google's documentation:

• Use full URLs, including https://. Relative paths such as /ar/services/ are not valid in hreflang.
• Return links are required. If the English page points to the Arabic one and the Arabic page does not point back, Google ignores the pair.
• Link the equivalent page, not the other language's homepage.
• Point only at URLs that return 200. A tag pointing at a redirect, a noindexed page or a page that canonicalises elsewhere sends mixed signals.
• Keep the tags in the head. If invalid markup above them makes the browser close the head early, they are ignored.

Our hreflang tag generator builds the block from a list of codes and URLs, and flags invalid codes before you publish them.

Which language and region codes are valid?

The language is an ISO 639-1 code. The region is optional, an ISO 3166-1 alpha-2 country code, written after a hyphen. Case does not matter, though ar-AE is the convention.

The ae row is a real trap. A region code on its own is never valid, and some two-letter country codes happen to be language codes. Google's documentation gives be as its example: it means Belarusian, not Belgium.

When should you use regional codes like ar-AE and ar-SA?

Only when the content differs by country: prices in different currencies, different phone numbers and addresses, different products, or different legal text. If one Arabic page serves every Arabic reader, use ar. Regional variants with identical content add maintenance and earn nothing.

When you do have regional versions, Google recommends also providing a version for the bare language, so Arabic readers outside the UAE and Saudi Arabia still have a match. That catch-all can be one of the regional pages:

<link rel="alternate" hreflang="en" href="https://example.com/" />
<link rel="alternate" hreflang="ar-AE" href="https://example.com/ar-ae/" />
<link rel="alternate" hreflang="ar-SA" href="https://example.com/ar-sa/" />
<link rel="alternate" hreflang="ar" href="https://example.com/ar-ae/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

The same URL can appear under more than one code. Here the UAE page also serves as the general Arabic page, and the English page doubles as the x-default.

Should you use HTML tags, HTTP headers or the sitemap?

Google treats the three methods as equivalent. Pick one. Using two or three adds maintenance and gives no benefit in Search.

In a sitemap, declare the xhtml namespace and give every URL its own url entry listing every alternate, including itself:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/services/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/services/" />
    <xhtml:link rel="alternate" hreflang="ar" href="https://example.com/ar/services/" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/services/" />
  </url>
  <url>
    <loc>https://example.com/ar/services/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/services/" />
    <xhtml:link rel="alternate" hreflang="ar" href="https://example.com/ar/services/" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/services/" />
  </url>
</urlset>

For a PDF brochure in two languages, the header method looks like this, sent with both files:

Link: <https://example.com/brochure.pdf>; rel="alternate"; hreflang="en", <https://example.com/ar/brochure.pdf>; rel="alternate"; hreflang="ar"

What mistakes stop hreflang from working?

Broken setups almost always have one of these:

• Missing return links. Usually an Arabic section added later, with the tags on the new pages but the English templates never updated.
• Relative URLs in the href.
• Invented codes: arabic, ae, en-UK, or a region on its own.
• A canonical pointing across languages. If the Arabic page's canonical tag points at the English page, you are telling Google the Arabic page is a copy to drop. Google's guidance is to specify a canonical in the same language; in practice, each page's canonical points at itself. Canonical tags explained covers the rest.
• Tags that point at redirects, often after a migration changed the URLs and nobody regenerated the tags.
• Tags added only by client-side scripts. Google can render JavaScript, but tags in the server-rendered HTML are read on the first pass and are easier to audit.

How do you check that hreflang is working?

Hreflang is one line on our technical SEO checklist, and checking it starts with the HTML. Open the page source of one page in each language and confirm that each lists every version, itself included, with full URLs. Then crawl the site with a crawler that reports hreflang, which will find missing return links across thousands of pages faster than you can by hand.

Search Console no longer has a dedicated report; Google retired its International Targeting report in 2022. Use URL Inspection instead. Inspect an Arabic URL and look at the canonical Google selected. If it is the Arabic URL itself, the language versions are understood. If Google chose the English URL, it believes the pages are duplicates, which usually means the main content was never translated or the Arabic page carries a cross-language canonical.

For the wider choices around hreflang, such as subfolders against country domains, read subdomain vs subfolder vs ccTLD. If the site runs on Next.js, the metadata API can generate the tags for you; building a multilingual Next.js site shows the setup.