SEO

Hreflang

Hreflang is an attribute that tells Google about the language- and region-specific versions of the same content, so search results surface the version that matches a user's language settings and location. For example, it can signal that UK users should see the en-gb page while US users see the en-us page.

Hreflang is an attribute that tells Google about the language- and region-specific versions of the same content so the most relevant version surfaces in search results.
It can be implemented in three ways — HTML link tags, HTTP headers, or an XML sitemap — and you pick one based on the nature of the page.
Language codes follow ISO 639-1 and region codes follow ISO 3166-1 Alpha 2; a region code used on its own is treated as invalid.
The most common mistake is a missing return link: if X points to Y, then Y must also point back to X.
The fallback version for users who match no available language is declared with the x-default value.

Overview

When the same content exists in multiple language- and region-specific versions, hreflang tells Google which language and region each version is intended for. Google uses this information to surface the version that fits a searcher's language settings and location. For example, when British English (en-gb), American English (en-us), and German (de) versions all exist, hreflang can signal that UK users should be served the en-gb page.

On multilingual and multi-regional sites, the absence of hreflang can lead Google to surface the wrong language version, or to treat near-identical versions as duplicate content and index only one of them. Hreflang is the signal that makes clear these versions are not duplicates but alternates aimed at different audiences.

Three Implementation Methods

Google supports three ways to declare hreflang. Use only one method per page, and in every method list all versions, including the page itself.

HTML Link Tags

Place one link element per version inside the <head> of each page. This is the most widely used method for standard HTML pages.

<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/" />

HTTP Headers

Non-HTML files such as PDFs have no <head>, so the versions are declared with a Link entry in the HTTP response header.

Link: <https://example.com/file.pdf>; rel="alternate"; hreflang="en",
      <https://de-ch.example.com/file.pdf>; rel="alternate"; hreflang="de-ch",
      <https://de.example.com/file.pdf>; rel="alternate"; hreflang="de"

XML Sitemap

For sites with many pages, declare the xhtml namespace in the sitemap and list each version with an xhtml:link element under the relevant url entry. This lets you manage everything in one place without editing the HTML.

<url>
  <loc>https://www.example.com/english/page.html</loc>
  <xhtml:link rel="alternate" hreflang="en"
              href="https://www.example.com/english/page.html"/>
  <xhtml:link rel="alternate" hreflang="de"
              href="https://www.example.de/deutsch/page.html"/>
</url>

Language and Region Code Format

Codes follow a language-region format. The language uses an ISO 639-1 code and the region uses an ISO 3166-1 Alpha 2 code.

Language alone is allowed: de, en
Language plus region: en-gb, de-ch
A script can be specified: zh-Hant, zh-Hans-US
A region code on its own is invalid: for instance, targeting Germany with a bare region code instead of de will not be recognized.

Common Errors

The mistakes flagged consistently by Google Search Central documentation and industry guides include the following.

Missing return link: if page X points to Y as an alternate, then Y must also point back to X. When only one side references the other, that hreflang annotation may be ignored.
Missing self-reference: each version must also include an hreflang pointing to itself. Without the self-reference, the relationship set is incomplete.
Missing or duplicate x-default: the fallback version for users who match no available language (such as a country selector page) is declared with x-default, and a page may have only one. If there are several, all of them are ignored.
Nonstandard or invalid codes: codes that fall outside the ISO standards, such as es-419, EU, or UK, are ignored.
404 or redirect targets: every URL referenced by hreflang must return 200 (OK) and be indexable. If it resolves to a 404 or a redirect, the signal may be ignored.
Conflict with canonical: when the canonical points to a URL different from the hreflang set, it creates a conflicting signal and Google may choose a URL other than the one you intended.

Supporting Sources

The implementation methods, code formats, and error cases above are spelled out in Google Search Central's official documentation, "Localized Versions of your Pages." That document states the return-link rule explicitly — "if page X links to page Y, page Y must link back to page X" — and advises that a region code cannot be used on its own. The x-default value was introduced by Google in a 2013 blog post ("Introducing x-default hreflang") for international landing pages.

Implementation Checklist

Confirm that every language and region version is listed without omission, and that each set includes the page itself.
Check that all versions reference one another bidirectionally (return links).
Verify that languages follow ISO 639-1 and regions follow ISO 3166-1 Alpha 2, and that no region code is used on its own.
Declare exactly one x-default for users who match no available language.
Confirm that every URL referenced by hreflang returns 200 and is indexable, and that none conflict with the canonical.
Use a single implementation method (HTML link, HTTP header, or sitemap) per page.