Hreflang:
What It Is and How to Use It

Hreflang identifies equivalent page URLs for different languages or regions, helping Google show the appropriate version in search, as described in Google’s localized-versions guide.

When to use hreflang#

Use hreflang for corresponding pages published at separate URLs for different languages or regional audiences. Multilingual sites offer more than one language; multi-regional sites target different countries. A site can do both, and Google’s international-site guidance recommends separate URLs for each language version rather than changing one URL’s content through cookies or browser settings.

Map each page to its actual counterparts. Keep this mapping at the page level: record the content identifier, language or region, and destination URL for every available version. Use the inventory to generate annotations whenever a version is published, moved, or removed. This is an implementation recommendation for maintaining the relationships, rather than a requirement to adopt a particular URL structure or content system.

Hreflang labels do not establish the language of the visible content. Google determines language from the page itself, rather than from the URL or HTML language attributes, according to its language-detection guidance. Keep the annotation’s language label consistent with the destination’s content.

Choose the correct language and region codes#

Google accepts ISO 639-1 language codes and optional ISO 3166-1 alpha-2 region codes, separated by a hyphen, under its supported-code rules.

Google also supports the script values shown above; its code guidance rejects country-only targeting and ignores reserved region codes such as UK. Use en-GB for UK English.

Implement hreflang in HTML, headers, or a sitemap#

Google treats HTML, HTTP headers, and XML sitemaps as equivalent methods; using all three provides no additional Search benefit.

Choose the method that the publishing system can update reliably. Keep one maintained page-to-locale inventory as the source of the annotations, especially when several templates or publishing services produce the final output.

HTML link tags#

The HTML syntax combines a relationship, a language label, and a destination. As the MDN link-element reference explains, rel describes the relationship, hreflang hints at the linked resource’s language, and href supplies its URL. Use rel="alternate" for the localized alternative.

Google requires fully qualified URLs and a valid HTML head. The following markup uses the placeholder URLs from Google’s English/German implementation example:

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

Publish both lines on both pages. Each page thereby identifies itself and its counterpart, matching the reciprocal structure in Google’s example. Replace the placeholder addresses with the actual corresponding URLs before using the markup.

Google ignores annotations between pages without return links.

HTTP response headers#

Google supports hreflang in GET response headers, including for non-HTML files such as PDFs.

The Web Linking standard, RFC 8288, defines the Link header syntax: place each target URL inside angle brackets and add semicolon-separated parameters. Multiple links can share a comma-separated header value. Applied to language alternatives, the syntax is:

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

Check the response headers separately from the HTML source. Keep the declared counterpart set synchronized across the responses, just as with the HTML implementation. Do not confuse the Link header’s language hint with the response’s own Content-Language: RFC 8288 explains that hreflang does not override that header.

XML sitemap annotations#

A sitemap can store the same relationships centrally. Google’s sitemap example gives each localized URL a separate entry containing alternate links to both versions. Declare the XHTML namespace required by Google on the sitemap root:

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

The two entries have different loc values and the same alternate list. Check both entries when updating the mapping; changing only the English entry leaves the German entry’s relationship unchanged.

Use x-default for a fallback destination#

The x-default value identifies a fallback for users whose language or region has no matching version. According to Google’s x-default explanation, the destination can be a language or country selector, or the content version designated as the default.

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

This line supplies a fallback URL; it does not describe an additional translation. Keep the normal language entries alongside it. A generic language entry such as en still identifies English content, while x-default covers unmatched audiences.

Google also explicitly permits hreflang on only part of a site. Include existing equivalents and leave unavailable translations out of the map. As an implementation recommendation, avoid assigning unrelated localized pages merely to fill every locale in an inventory.

Keep hreflang and canonical annotations separate#

A canonical annotation expresses the preferred URL among duplicate or very similar pages. For pages using hreflang, Google’s canonical guidance calls for a canonical in the same language when available, or the best substitute language when one is not.

For a translated page intended to represent its language, a self-referencing canonical is a practical starting point. Resolve duplicate URLs within that language before generating the alternate mapping. Do not automatically point every translation’s canonical at the original-language URL; that can contradict the intended language representatives.

Keep the two declarations distinct. Google ignores canonical annotations that also carry hreflang; its canonical implementation rules call for separate rel="canonical" and rel="alternate" links.

Treat a canonical declaration as a preference to check, rather than proof of Google’s selection. Regional pages in the same language also need this check when their content substantially overlaps.

Check common hreflang errors#

Begin with the published URLs and the declarations they actually return. Use this order to locate the part of the implementation that needs correction:

1. Check access to every destination. Open each URL directly and record the final URL after any redirects. Avoid forced language redirects: Google warns that they can prevent users and crawlers from reaching all versions. Provide visible links for changing languages.
2. Compare the alternate lists. Check the deployed HTML head, response header, or sitemap entry for each counterpart. Look for an omitted self-reference, a missing counterpart, an old destination, or a mismatch between the code and the page language.
3. Check crawling and indexing separately. In Search Console, URL Inspection reports crawl permission, page-fetch status, and indexing permission. Review these fields for localized URLs intended to appear in search. A successful live test does not guarantee indexing.
4. Compare declared and selected canonicals. The Google-selected canonical field is available in the indexed data. The live test cannot predict canonical selection; its response inspection can help check current HTML and headers.
5. Investigate unexpected canonical choices. Google’s troubleshooting guidance recommends reviewing canonical elements, redirects, server configuration, localization annotations, and content similarity. Correct the underlying mismatch before repeatedly changing hreflang labels.

After changing the mapping, check every affected counterpart again. Google’s canonical troubleshooting documentation notes that re-evaluation takes time. Record the deployed declarations and the indexed observations separately so that an older crawl is not mistaken for the current implementation.