PerfoMetrix

All guides · SEO

hreflang: Language Versions Search Engines Understand

If your site has the same content in several languages or for several regions, hreflang annotations tell search engines which version belongs to which audience. A searcher in Germany then sees your German page, and one in the UK sees the British English page, instead of whichever version happens to rank.

hreflang is a hint, not a redirect, and it does not move rankings by itself. It helps the right version appear for the right person, and stops language versions being treated as duplicates of each other.

The format

The most common form is a set of link elements in the head of every version:

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

The rules that matter:

  • Codes. A language code from ISO 639-1 (en, de, pt), optionally followed by a region from ISO 3166-1 alpha-2 (en-GB, pt-BR). A script subtag is possible where it matters (zh-Hant). A region on its own (GB) is not valid.
  • x-default marks the fallback for visitors who match none of the listed languages, often a language picker or your main version. It is optional but recommended.
  • Absolute URLs, including the scheme. Relative paths are not reliably understood.
  • Every version lists every version, including itself. The German page carries the same set of links as the English one.
  • Links must be reciprocal. If page A says B is its German version, B must point back to A. Google ignores one-sided annotations.
  • One URL per code. Two different URLs for en-GB contradict each other.
  • Point at canonical URLs that return 200, not at redirects or pages with a different canonical.

Common mistakes

  • en-UK instead of en-GB. The region code for the United Kingdom is GB.
  • jp for Japanese (the language code is ja; JP is the country), or se for Swedish (sv).
  • Using underscores (en_GB) instead of hyphens.
  • Copying the same block to every page but forgetting the page’s own entry.
  • Annotating only the home page, when each translated page needs its own set.

Where to put it

There are three equivalent places: link elements in the HTML, a Link HTTP header (useful for PDFs), or xhtml:link entries in the XML sitemap. Use one method consistently; mixing them makes errors harder to find. For large sites, the sitemap is usually easiest to generate.

WordPress: multilingual plugins such as WPML and Polylang output hreflang automatically once translations are linked to each other. Missing self-references or missing pages usually mean a translation is not connected to its original in the plugin.

Nginx, for files that are not HTML:

location = /docs/guide.pdf {
  add_header Link '<https://example.com/docs/guide.pdf>; rel="alternate"; hreflang="en", <https://example.com/de/docs/guide.pdf>; rel="alternate"; hreflang="de"';
}

How PerfoMetrix checks this

We read the link rel="alternate" elements with an hreflang attribute in the HTML we already downloaded. We send no extra requests to your site, so we do not check that the other versions exist or link back; Search Console’s international targeting reports and crawler tools can do that.

The check needs attention when a code does not look like a language code (optionally with script and region) or x-default, when a code appears twice, when a URL is relative, or when the page does not list itself. A missing x-default is reported but not counted as a problem. Pages without hreflang get an information result: single-language sites do not need it.

Our pattern also accepts three-letter language codes and numeric regions such as es-419, which are valid language tags in general; Google’s documentation describes ISO 639-1 and ISO 3166-1 alpha-2 codes, so prefer those. We cannot tell en-UK from a real region code, so check that one by eye.

Further reading: Google: localized versions of your pages.

Last updated October 28, 2026

Scan your website