How to Use Hreflang: Implementation Guide for SEO

To learn how to use hreflang across an international website, map every language variation of a page and deliver reciprocal links among all versions, including a self-referencing link for the page itself. Search engines use these annotations to display the correct regional or linguistic URL to users based on their location and browser language settings. You can implement this mapping using HTML head tags, HTTP response headers, or an XML sitemap.

Which hreflang implementation method should you choose?

Google supports three distinct methods for deploying hreflang annotations. Each serves different technical architectures, but all three achieve the exact same goal in search results. You should pick one method per section of content rather than mixing them for the same URL.

Method	Best For	Key Trade-Off
HTML Link Tags	Small to medium sites with static or CMS-managed templates	Adds page weight and code to the HTML head as language counts grow
HTTP Response Headers	Non-HTML files such as PDFs and dynamically served documents	Requires direct access to web server configuration files
XML Sitemaps	Enterprise platforms and large stores with dozens of localized locales	Keeps HTML lean, but sitemap files require automated maintenance

For most standard websites, HTML link tags in the document head are the simplest to read and test. If you manage a site translated into dozens of languages, putting the markup into an XML sitemap keeps page load times fast by preventing head bloat.

Generate complete clusters with the Links to Wild Hreflang Generator

The fastest way to produce clean, error-free markup across multiple URLs is with the Hreflang Generator. This browser-based tool builds the complete reciprocal set so you do not have to write repetitive tags by hand.

1. Open the generator in your web browser. All parsing and tag creation runs entirely inside your browser session, so nothing you enter is sent to a server, uploaded, or logged.
2. Enter your primary URL and select its ISO 639-1 language code (for example, en for English). Add an ISO 3166-1 alpha-2 region code only if the content is tailored to a specific country (such as en-GB for the United Kingdom).
3. Add each alternate language or regional variation URL alongside its respective language and country codes.
4. Specify an x-default URL to catch searchers whose language settings do not match any of your specified versions.
5. Select your preferred output format: HTML link tags, HTTP response headers, or XML sitemap syntax.
6. Copy the resulting reciprocal block directly into your website templates, server configuration, or sitemap file.

Add hreflang tags directly to your HTML head

When working on smaller multilingual blogs or corporate sites, you can place <link> tags directly inside the <head> section of your HTML template. When learning how to use hreflang tags for international seo, remember that every single localized page must include tags for itself and all alternate versions.

A complete implementation across English, Spanish, and a global fallback looks like this:

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

1. Open your website base template or header file in a code editor.
2. Identify the <head> element, making sure your cursor sits before the closing </head> tag and ahead of any scripts that could prematurely close the head block.
3. Add a self-referencing rel="alternate" link pointing to the URL of the current page with its assigned language code.
4. Add a line for every alternate regional or translated version of that specific page.
5. Add the x-default tag to assign a fallback destination for unmatched languages, such as an international selector landing page.
6. Repeat this identical cluster across the <head> of every listed page in the group so that all versions point to each other.

Implement hreflang via HTTP response headers

HTML tags cannot be placed inside non-HTML assets like downloaded PDFs, spreadsheets, or raw text files. In these cases, you can deliver hreflang instructions through the server response headers when the asset is requested.

The HTTP header format delivers comma-separated values inside a single Link directive:

Link: <https://example.com/brochure.pdf>; rel="alternate"; hreflang="en", <https://example.com/es/folleto.pdf>; rel="alternate"; hreflang="es", <https://example.com/brochure.pdf>; rel="alternate"; hreflang="x-default"

1. Access your web server configuration file (such as .htaccess or httpd.conf on Apache, or your server block in Nginx).
2. Identify the target directory or file type containing the localized assets.
3. In Apache, use mod_headers to attach the header. For example:
   <Files "brochure.pdf">
  Header add Link "<https://example.com/brochure.pdf>; rel=\"alternate\"; hreflang=\"en\", <https://example.com/es/folleto.pdf>; rel=\"alternate\"; hreflang=\"es\""
</Files>
4. In Nginx, add the directive inside the matching location block:
   location = /brochure.pdf {
  add_header Link '<https://example.com/brochure.pdf>; rel="alternate"; hreflang="en", <https://example.com/es/folleto.pdf>; rel="alternate"; hreflang="es"';
}
5. Restart or reload your web server, then test the live headers using an HTTP inspection command like curl -I https://example.com/brochure.pdf.

Deploy hreflang in XML sitemaps for large websites

If your website serves dozens of markets, adding 50 link tags to the head of every page adds unnecessary payload to page load times. Moving the markup into an XML sitemap isolates the international configuration entirely.

An XML sitemap entry declares each URL once with child elements that list all sister variants:

<url>
  <loc>https://example.com/page</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/page"/>
  <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/pagina"/>
  <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page"/>
</url>

1. Ensure your sitemap root node declares the XHTML namespace: xmlns:xhtml="http://www.w3.org/1999/xhtml".
2. For each URL node (<url>), define the page location in the standard <loc> tag.
3. Underneath the <loc> tag, list every alternate URL (including the URL itself) inside an <xhtml:link> element.
4. Repeat this complete list of child <xhtml:link> tags for every language URL entry in the sitemap.
5. Validate your output with an XML Sitemap Validator to ensure proper namespace formatting, syntax, and absence of broken URLs.
6. Submit the sitemap index to Google Search Console.

Configure hreflang inside your CMS settings

Modern content management systems usually rely on plugins or built-in localization suites to handle international tags. Understanding how to use hreflang tags within these platforms prevents manual coding mistakes across dynamic collections.

1. WordPress: Install a translation plugin such as WPML or Polylang. Navigate to the plugin settings and establish your base language and target locales. The plugin monitors page translation relationships and automatically injects self-referencing and reciprocal links into the document head.
2. Shopify: In your store admin, navigate to Settings > Markets. Add target countries, assign localized subfolders or custom regional domains, and enable automated market redirection. Shopify handles the injection of alternate link tags into theme.liquid automatically.
3. Webflow: Open Site Settings > Localization. Add your secondary locales, set directory prefixes (like /es or /fr), and toggle on automatic hreflang generation in your publishing options.

Common hreflang mistakes and how to check hreflang

Hreflang errors are notoriously common because the syntax requires absolute precision. When search engines encounter conflicting signals, they simply drop the annotations and revert to standard algorithmic matching.

Missing return tags

The most frequent failure occurs when page A points to page B, but page B fails to point back to page A. Google requires complete confirmation from both sides of the relationship to avoid spoofing. If one page in a set lacks a link back to any sibling, the entire cluster breaks down.

Canonical tag conflicts

Your canonical tag and hreflang tags must tell the exact same story. If https://example.com/es/pagina points its canonical tag to https://example.com/page, search engines will ignore the Spanish version for indexing. Each language variation should point its canonical tag to itself. You can verify your canonical configuration with our canonical tag implementation guide.

Incorrect language and country codes

You cannot invent custom shorthand for countries or languages. Language codes must follow ISO 639-1 (two letters, such as en, es, or de), and optional region codes must follow ISO 3166-1 alpha-2 (such as GB, US, or AU). Using en-UK instead of en-GB will cause Google to ignore the directive.

How to check your implementation

To inspect your setup, open the published page in a browser, view the rendered source code, and inspect the <head> section. Verify that every URL uses absolute syntax (including https://) and that trailing slashes match your site canonical structure precisely.

In Google Search Console, use the URL Inspection tool on any translated page to review the crawled page HTML. If you are building out new clusters, you can verify your syntax and export clean blocks using the free Hreflang Generator before deploying updates to your production environment.

If you are launching international storefronts or regional sites that need to rank against domestic competitors, technical tags only solve half the challenge. Strong localized domains also require regional authority. If you want support earning placements in specific geographic markets, you can review our link building pricing and packages.

Frequently Asked Questions

Do I need hreflang if my site is only in one language?

No. Hreflang exists to disambiguate between different language or regional versions of the same content. With only one version of a page, there is nothing for a search engine to disambiguate. Adding self-referencing hreflang tags to a monolingual website does nothing at all, neither good nor bad.

Is the region code required?

No, and most sites should not use one. The tag es serves every Spanish speaker worldwide. The tag es-MX restricts that URL preference to Spanish speakers located in Mexico. You should only use a region code when you have country-specific content, such as distinct currency, pricing, shipping restrictions, or legal terms, not simply because the copy was written in a particular office.

Why does Search Console say "no return tags"?

Search Console flags "no return tags" when the alternate page you pointed at does not point back to the source page. Inspect the rendered head of the destination page. Common causes include building the cluster only on the original page, mismatched trailing slashes between URLs, or injecting tags through client-side JavaScript that the search engine crawler did not execute.

Does the order of the tags matter?

No. Search engines read the entire cluster regardless of which order the tags appear in. The strict rule regarding placement is that HTML link tags must reside completely inside the <head> element. If a syntax error earlier in the page breaks the head and pushes your tags into the <body>, crawlers will ignore them.

Is anything I paste into the Links to Wild tool sent anywhere?

No. The tool runs without a backend service. All URL parsing and code generation take place directly within your browser, meaning nothing you paste is uploaded, logged, or stored.