Knowledge Base › Hreflang Manager › Setup

Hreflang Fundamentals and Implementation Guide

If you are already familiar with how hreflang works, you can safely skip this document and go straight to the page that explains how to add hreflang data. Otherwise, this page will give you the essential foundation you need before configuring the Hreflang Manager plugin.

What Is Hreflang?

Hreflang is a method used to tell search engines which language or regional version of a page should be served to users. Google’s official documentation provides the full technical details, but the purpose of this guide is to help you understand the fundamentals before using Hreflang Manager.

What Does Hreflang Indicate?

The hreflang attribute is used to indicate:

  • Language variations (e.g., English vs. Spanish)
  • Script variations (e.g., Traditional Chinese vs. Simplified Chinese)
  • Regional variations (e.g., English for the United States vs. English for the United Kingdom)

Search engines use hreflang to display the most appropriate version of a page to users based on language preferences and geographic signals.

How Hreflang Works

When a user performs a search, search engines attempt to serve:

  • A version of the page in the user’s preferred language
  • A version targeted to the user’s geographic region
  • Fallback options when no perfect match exists

For example, a Spanish-speaking user in Mexico may receive:

  • es-mx (ideal match)
  • es (general Spanish)
  • x-default (fallback version)

Methods for Adding Hreflang to a Website

There are three official methods for implementing hreflang. All three methods function the same from a search engine perspective, use whichever method best fits your setup.

1. HTML Tags

The most common method is to insert an HTML tag into the <head> section of each page.

<link rel="alternate" href="https://example.com/fr/" hreflang="fr" />

An hreflang tag is an HTML link element with three key components:

  • rel="alternate" indicates the linked page is an alternative version
  • href defines the URL
  • hreflang specifies the language, script, and region

Example structure:

<link rel="alternate" href="https://example.com/fr/" hreflang="fr" />
<link rel="alternate" href="https://example.com/fr-ca/" hreflang="fr-ca" />
<link rel="alternate" href="https://example.com/" hreflang="x-default" />

When you should use this method:

  • You want signals embedded directly into the page
  • Your site has a small or moderate number of languages
  • Your server setup cannot generate XML sitemaps

The implementation of hreflang via HTML Tags is the default method used by Hreflang Manager. To enable or disable it, go to the Options → General tab, activate or deactivate the HTML Tags toggle, and save the settings.

2. XML Sitemaps

Hreflang annotations can also be added inside XML sitemaps, which is especially useful when you cannot modify the HTML of your pages.

Example of an XML sitemap containing hreflang annotations:

<?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/</loc>
        <xhtml:link
                rel="alternate"
                hreflang="en"
                href="https://example.com/"/>
        <xhtml:link
                rel="alternate"
                hreflang="de"
                href="https://example.com/de/"/>
    </url>
    <url>
        <loc>https://example.com/de/</loc>
        <xhtml:link
                rel="alternate"
                hreflang="en"
                href="https://example.com/"/>
        <xhtml:link
                rel="alternate"
                hreflang="de"
                href="https://example.com/de/"/>
    </url>
</urlset>

Advantages of using XML sitemaps for hreflang:

  • No impact on page size or performance
  • No need to modify templates or inject <link> tags
  • Handles very large numbers of localized URLs efficiently
  • Reduces the risk of incorrect or missing hreflang entries
  • Works for non-editable or non-HTML pages
  • Easier SEO debugging and validation through a central file

Hreflang Manager supports implementing hreflang via XML sitemaps. To enable this feature, go to Options → General and activate the XML Sitemap toggle. The sitemap will be available at /hreflang-sitemap.xml:

Example: https://example.com/hreflang-sitemap.xml

3. HTTP Response Headers

Typically used for non-HTML files, such as PDFs.

Example:

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

Advantages of using HTTP headers:

  • Works for non-HTML files such as PDFs or other media
  • No need to modify the HTML output
  • Zero impact on page size or render performance
  • Ideal for API-driven or headless architectures
  • Can be managed centrally at the server or CDN level
  • Works reliably with multilingual CDN environments

Hreflang Manager does not currently support implementing hreflang via HTTP headers.

What Search Engines Do with Hreflang

Search engines use hreflang for:

  • Correct Language Matching – To serve users a page in their preferred language whenever possible.
  • Regional Targeting – To display country-specific versions when multiple variants exist.
  • Preventing Duplicate Content Issues – Because hreflang clarifies that similar pages target different audiences.
  • Avoiding Wrong-Page Rankings – Without hreflang, one country’s page may incorrectly rank in another country.
  • Fallback Behavior – When no exact match exists, search engines fall back to the generic language version (e.g., es) or the global fallback (x-default).

ISO Codes for Language, Script, and Region

Hreflang values use standardized ISO codes.

Language Codes – ISO 639-1

Used when content is targeting multiple languages.

Examples:

  • en (English)
  • es (Spanish)
  • fr (French)

Full list: List of ISO 639 language codes

Script Codes – ISO 15924

Used when languages exist in multiple scripts.

Examples:

  • zh-Hans (Simplified Chinese)
  • zh-Hant (Traditional Chinese)

Full list: ISO 15924

Region Codes – ISO 3166-1 Alpha-2

Used for regional variations.

Examples:

  • en-gb (English for the United Kingdom)
  • en-ca (English for Canada)

Full list: ISO 3166-1 alpha-2

Complete Hreflang Value Format

[language][-script][-region]

Examples:

  • en
  • en-US
  • zh-Hans-CN

Core Hreflang Requirements You Must Follow

If Page A references Page B, Page B must also reference Page A. Missing reciprocity is one of the most common hreflang errors.

2. Self-Referencing Tags

Each page must include a self-referencing hreflang annotation.

3. Provide a Global Fallback (Optional but Recommended)

Use x-default for language-selection or global pages.

Common Hreflang Mistakes to Avoid

  • Missing backlink reciprocity
  • Incorrect or non-standard ISO codes
  • Linking to non-canonical URLs
  • Mixing different implementation methods
  • Missing self-referencing tags
  • Linking pages that are not true equivalents

Hreflang Manager includes a complete audit tool to detect these errors. For more information, see the section dedicated to the Hreflang Checker.

These external resources provide additional explanations and best practices:

Key Terminology

Here are the core concepts you should know before working with hreflang:

Language Code

The first part of an hreflang value, defined by ISO 639-1 (e.g., en, fr, es). Represents the primary language.

Script Code

The optional second part of an hreflang value used to indicate the script variation of the language, defined by ISO 15924.

Region Code

The optional third part of an hreflang value, defined by ISO 3166-1 Alpha-2 (e.g., US, GB, CA). Specifies the target country or region.

Language-Region Combination

A full hreflang value combining language and region (e.g., en-GB = English for the United Kingdom). Helps refine targeting and avoid showing generic versions to country-specific audiences.

Self-Referencing Tag

Every page must include an hreflang tag pointing to itself to prevent search engines from interpreting the page as incomplete or incorrectly configured.

Reciprocal Tags

The mandatory bidirectional linking between page variations. If an English page links to a Spanish equivalent, the Spanish page must point back to the English one.

X-Default

A special hreflang value used to indicate the fallback or global URL when no more specific version exists. Commonly used for language selectors.

Hreflang Cluster

A group of URLs representing all language/region variations of the same content. Search engines evaluate them as a set; missing or incorrect URLs affect the entire cluster.

Alternate URL

A localized (in terms of language, script, or region) version of the same content.

Final Notes Before Using Hreflang Manager

Before configuring your site, make sure you:

  • Know which pages are localized equivalents
  • Understand the language/script/region structure of your site or your network of sites
  • Have all page mappings ready

Once these fundamentals are clear, using the plugin becomes straightforward.