How hreflang Works

When a website has multiple language or regional versions of the same content, search engines need to understand which version is intended for which audience. A visitor in France may need a French page, while a visitor in Canada may need a French or English version designed specifically for that market. This is where hreflang comes in.

hreflang is an HTML link attribute and related XML sitemap mechanism used to tell search engines about alternate language and regional versions of a page. It does not translate content, redirect users automatically or guarantee that a particular URL will appear in a particular country.

The main purpose of hreflang is to describe relationships between equivalent pages that target different languages or regions. When implemented correctly, it gives search engines additional information about which version is appropriate for a particular audience.

What Is hreflang?

hreflang is an attribute used to identify the language and, optionally, the regional audience of an alternate version of a page.

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

The hreflang value fr indicates that the referenced URL is intended for French-language users. The href attribute contains the corresponding page URL.

For a multilingual website, several alternate URLs can reference each other.

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

Why hreflang Is Needed

Imagine that the same product information exists in English, French and German. The pages may be very similar structurally and may contain largely equivalent information, but they are intended for different language audiences.

Without explicit language relationships, a search engine has to infer how these URLs relate to each other. hreflang provides an additional signal describing the intended language and regional audience.

This is particularly useful when several versions are legitimate pages rather than accidental duplicates.

hreflang Does Not Translate a Page

hreflang does not translate content. You need to create and maintain the actual language versions yourself or through your content system.

For example, adding hreflang="de" to an English page does not turn that page into a German page. It simply declares that the referenced URL is intended for German-language users.

Language Codes

The language part of hreflang follows standard language-code conventions. Common values include en for English, fr for French, de for German, es for Spanish and it for Italian.

Language codes should represent the actual language of the referenced page. Do not use arbitrary abbreviations simply because they look familiar.

Language and Region Together

hreflang can also specify a region. The general structure is language followed by a hyphen and a two-letter country or region code.

<link
  rel="alternate"
  hreflang="en-US"
  href="https://example.com/en-us/product"
/>
<link
  rel="alternate"
  hreflang="en-GB"
  href="https://example.com/en-gb/product"
/>

Here en-US means English intended for the United States, while en-GB means English intended for the United Kingdom.

The distinction matters when the content, currency, shipping information, legal requirements or other details differ by market even though the language is the same.

Language vs Regional Targeting

Using a regional code does not mean that the language is ignored. en-US still represents English, with the United States providing the regional qualification.

When Should You Use Region-Specific hreflang?

Use a regional value when separate URLs genuinely target different markets. For example, an online store may have different English pages for the United States and United Kingdom because prices, currency, shipping and product availability differ.

If there is only one English version for all English-speaking users, en may be more appropriate than creating unnecessary regional variants.

The x-default Value

The special x-default value can identify a fallback page for users whose language or region does not match one of the specified alternatives.

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

A common use case is a language-selection page or a general international version of a website.

x-default is not a language. It identifies a fallback URL when no more specific hreflang alternative is appropriate.

The Most Important Rule: hreflang Should Be Reciprocal

If page A declares page B as an alternate version, page B should also declare page A as an alternate. The same principle applies to every page in the hreflang cluster.

<!-- English page -->
<link
  rel="alternate"
  hreflang="en"
  href="https://example.com/en/product"
/>
<link
  rel="alternate"
  hreflang="fr"
  href="https://example.com/fr/product"
/>

<!-- French page -->
<link
  rel="alternate"
  hreflang="en"
  href="https://example.com/en/product"
/>
<link
  rel="alternate"
  hreflang="fr"
  href="https://example.com/fr/product"
/>

If the relationship exists in only one direction, the implementation is incomplete. Reciprocal references make the intended group of alternatives explicit.

Every Version Should Usually Reference the Complete Set

For a group containing English, French and German versions, each version should generally identify all relevant alternatives, including itself.

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

The self-reference is important because it makes the page's membership in the hreflang set explicit.

Self-Referencing hreflang

A page should normally include an hreflang entry pointing to its own URL in addition to the alternate versions.

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

For example, the English version includes the en entry pointing back to itself, while the French version includes the fr entry pointing to itself.

Canonical URLs and hreflang

Canonical URLs and hreflang solve different problems and should not be treated as competing mechanisms.

Canonical tells search engines which URL is the preferred representative of a page or set of duplicate or substantially similar URLs. hreflang describes alternative language or regional versions of the content.

<link
  rel="canonical"
  href="https://example.com/en/product"
/>

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

On a multilingual site, each localized page will commonly have a self-referencing canonical URL while also participating in the hreflang relationship with the other localized pages.

hreflang and Duplicate Content

Multilingual pages can contain similar or translated content without being accidental duplicates. hreflang helps search engines understand the intended relationship between those legitimate alternatives.

However, hreflang is not a way to make unrelated duplicate pages acceptable. If two URLs contain essentially the same content for the same audience, canonicalization or URL consolidation may be more appropriate.

Three Ways to Implement hreflang

There are three common implementation methods: HTML link elements, HTTP response headers and XML sitemaps.

Method 1: HTML link Elements

For ordinary HTML pages, hreflang can be declared in the document head using link elements.

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

This approach is easy to understand because the relationship is directly attached to each HTML document.

Method 2: HTTP Headers

For resources that are not HTML documents, hreflang can be expressed through HTTP response headers.

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

This method can be useful for resources such as PDFs where adding HTML link elements is not possible.

Method 3: XML Sitemap

Large multilingual websites can declare hreflang relationships in XML sitemaps. This moves the relationship data out of individual HTML documents and into centralized sitemap data.

<url>
  <loc>https://example.com/en/product</loc>
  <xhtml:link
    rel="alternate"
    hreflang="en"
    href="https://example.com/en/product"
  />
  <xhtml:link
    rel="alternate"
    hreflang="fr"
    href="https://example.com/fr/product"
  />
</url>

The sitemap approach can be useful when a site has thousands or millions of localized URLs and the application already has a centralized system for generating sitemap data.

Which hreflang Method Should You Use?

For a smaller website, HTML implementation is often the easiest to inspect and maintain. For large sites, sitemap-based implementation can be easier to centralize because localized URL relationships can be generated from the site's content data.

The important requirement is consistency. Avoid maintaining several independent hreflang systems that can easily become out of sync unless there is a clear reason to do so.

Absolute URLs Are Important

hreflang URLs should be fully qualified URLs rather than relative paths.

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

Using complete URLs makes the relationship explicit and avoids ambiguity across different hosts, protocols and document locations.

Use the Correct Protocol and Host

If the production site uses HTTPS, the hreflang URLs should normally use the canonical HTTPS URLs. Do not accidentally reference staging hosts, HTTP versions or unrelated domains.

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

A simple URL mistake can break the relationship even when the language codes themselves are correct.

hreflang for Different URL Structures

There is no requirement for every language to use the same URL structure. A website can use subdirectories, subdomains or separate country domains.

The important part is that each URL correctly identifies the intended language or region and that the references are reciprocal.

hreflang with Country Domains

Separate country-code top-level domains can naturally represent regional targeting, but hreflang can still explicitly describe the language and regional relationship between the pages.

<link
  rel="alternate"
  hreflang="fr-FR"
  href="https://example.fr/produit"
/>
<link
  rel="alternate"
  hreflang="fr-CA"
  href="https://example.ca/produit"
/>

The domain itself and hreflang provide different signals. A country domain can indicate a market, while hreflang describes the language and regional targeting of the alternate URL.

hreflang for English-Speaking Markets

English is a common example of a language that may need regional variants. A site could have separate pages for the United States, United Kingdom and Australia.

<link
  rel="alternate"
  hreflang="en-US"
  href="https://example.com/en-us/product"
/>
<link
  rel="alternate"
  hreflang="en-GB"
  href="https://example.com/en-gb/product"
/>
<link
  rel="alternate"
  hreflang="en-AU"
  href="https://example.com/en-au/product"
/>

This can be appropriate when the pages genuinely differ by market. If all three pages are identical and there is no meaningful regional distinction, maintaining separate URLs may add unnecessary complexity.

hreflang for the Same Language in Multiple Countries

The same language can have several regional variants. French is another example: fr-FR and fr-CA can represent French content intended for France and Canada respectively.

Regional differences can involve spelling, terminology, currency, product availability, shipping, regulations or other market-specific information.

What Happens If a Region Is Missing?

A website does not have to create a separate regional URL for every country in which a language is spoken. A general language version can cover users for whom no more specific regional alternative exists.

<link
  rel="alternate"
  hreflang="en"
  href="https://example.com/en/product"
/>
<link
  rel="alternate"
  hreflang="en-US"
  href="https://example.com/en-us/product"
/>

The general en version can serve as the broader English-language alternative, while en-US identifies a more specific regional version.

Common hreflang Mistakes

One of the most common errors is missing reciprocal references. A French page may point to the English page while the English page does not point back to the French page.

Another mistake is using invalid or incorrectly formatted language and region codes. The values should follow the expected language and regional code conventions rather than arbitrary abbreviations.

Incorrect URLs are also common. A single typo, HTTP URL or staging hostname can make an otherwise correct hreflang relationship point to the wrong resource.

Canonical conflicts are another problem. If localized pages all canonicalize to one language version, the hreflang relationship may no longer reflect the site's intended canonical structure.

Finally, developers sometimes generate hreflang tags for every possible language on every page even when the corresponding content does not actually exist. An alternate URL should point to a real, relevant version of the page.

Do Not Point hreflang to Redirects

hreflang references should point directly to the intended localized URL rather than relying on chains of redirects.

If a localized URL has permanently moved, update the hreflang relationship to the final URL rather than leaving the old address in the hreflang set.

Do Not Point hreflang to Error Pages

Every alternate URL should resolve to an actual page intended for the corresponding language or region. Broken URLs, missing pages and irrelevant alternatives make the hreflang cluster unreliable.

hreflang and Redirects

Redirects and hreflang can coexist, but the hreflang references themselves should describe the final localized destinations. When URL structures change, update the hreflang data together with redirects and canonical URLs.

hreflang on Dynamic Websites

Large applications usually generate hreflang relationships from content data rather than hard-coding every link. For example, a product record might contain localized URLs for English, French and German versions.

const alternatives = [
  {
    language: "en",
    url: "https://example.com/en/product",
  },
  {
    language: "fr",
    url: "https://example.com/fr/product",
  },
  {
    language: "de",
    url: "https://example.com/de/product",
  },
];

The application can then use the same source of truth to generate HTML metadata, sitemap entries or both. This reduces the chance that one part of the system contains a different set of localized URLs.

hreflang in Next.js

In Next.js, hreflang can be generated through the metadata system. The exact implementation depends on the routing architecture and whether localized routes are generated statically or dynamically.

export const metadata = {
  alternates: {
    canonical: "https://example.com/en/product",
    languages: {
      en: "https://example.com/en/product",
      fr: "https://example.com/fr/product",
      de: "https://example.com/de/product",
    },
  },
};

The important part is that the generated HTML contains the intended alternate language relationships. Always inspect the final rendered page rather than relying only on the source configuration.

Testing hreflang

Testing should begin with a single group of localized pages. Pick one English, one French and one German URL and verify that every page references the complete expected set.

It is also useful to inspect the generated HTML and sitemap directly. Automated validation can detect missing return references, invalid URLs and inconsistent language sets before these errors reach production.

A Complete hreflang Example

<head>
  <link
    rel="canonical"
    href="https://example.com/en/product"
  />

  <link
    rel="alternate"
    hreflang="en"
    href="https://example.com/en/product"
  />
  <link
    rel="alternate"
    hreflang="fr"
    href="https://example.com/fr/product"
  />
  <link
    rel="alternate"
    hreflang="de"
    href="https://example.com/de/product"
  />
  <link
    rel="alternate"
    hreflang="x-default"
    href="https://example.com/"
  />
</head>

The English page in this example declares itself, the French and German alternatives and a general fallback page. The French and German pages should contain equivalent reciprocal declarations with their own canonical URLs.

A Practical hreflang Workflow

Start by identifying which pages are true language or regional equivalents. Do not create hreflang relationships between pages that merely happen to belong to the same site.

Next, define the language and regional codes for each version. Keep the mapping in one source of truth whenever possible, especially when the site has a large number of localized pages.

Then choose an implementation method. HTML is straightforward for ordinary pages, while XML sitemaps can be easier to manage for large multilingual sites.

Make every relationship reciprocal, include self-references and verify that each URL is the correct canonical production URL. If an x-default page is useful, add it consistently.

Finally, validate representative pages and monitor the generated output after routing or localization changes. hreflang is closely connected to URL architecture, so changes to localized routes should trigger a review of the alternate mappings.

hreflang and Automatic Language Redirects

Some websites automatically redirect visitors based on browser language or geographic location. This can make localization convenient for users, but aggressive automatic redirects can complicate crawling and direct URL access.

A robust multilingual architecture should allow users and crawlers to access stable localized URLs directly. hreflang should describe those URLs rather than depending on a redirect system to infer the correct language.

Do You Need hreflang for Every Multilingual Site?

hreflang is most useful when multiple URLs represent corresponding language or regional versions of the same content. A very small site with one language version and no regional alternatives has no need for hreflang.

Likewise, creating multiple localized URLs without genuinely localized content can add unnecessary complexity. The URL structure, content strategy and audience targeting should come first; hreflang should describe that architecture.

Frequently Asked Questions

Helpful SEO Tools

An hreflang Generator can help create alternate language and regional link elements from a set of localized URLs. A Canonical URL Generator is useful for checking the preferred URL for each localized page, while a Meta Tag Generator can help manage related page metadata. An Open Graph Generator can be used to create social-sharing metadata for localized pages, and a URL Builder can help construct and inspect consistent URLs when working with multiple language or regional versions.

Conclusion

hreflang is a way to describe relationships between localized versions of a website. It does not translate pages, redirect users or replace canonical URLs. Its main purpose is to give search engines explicit information about language and regional alternatives.

A reliable hreflang implementation starts with correct URL architecture and then connects genuine language or regional equivalents. Each page should normally reference itself and its alternatives, the relationships should be reciprocal, and the URLs should point directly to valid production pages.

For smaller sites, HTML link elements can be straightforward to maintain. Larger multilingual sites may benefit from generating hreflang through XML sitemaps or from a centralized localization data model. Regardless of the implementation method, validation is essential because a single incorrect URL or missing reciprocal reference can make an otherwise large hreflang configuration inconsistent.