How to Implement hreflang Tags for International : A Step-by-Step Technical Guide

By / November 5, 2025

Implementing hreflang tags is crucial for international , as it tells search engines like Google which language and regional version of a page to serve users. Correct technical implementation prevents duplicate content issues and improves user experience globally.

Here is a step-by-step technical guide to implementing hreflang tags using the three approved methods.

1. Understand the Core hreflang Syntax and Rules

The hreflang tag is an HTML attribute that specifies the language and, optionally, the region of an alternative version of a page.

The Basic Tag Structure

The general format is:

HTML

<link rel="alternate" hreflang="language_code-region_code" href="Absolute_URL_of_alternate_page" />
  • rel="alternate": Indicates the link is an alternative version of the current page.
  • hreflang="x": Specifies the target language (and optional region).
    • Language Codes: Must use the two-letter ISO 639-1 format (e.g., en, es, fr).
    • Region Codes (Optional): Must use the two-letter ISO 3166-1 Alpha 2 format (e.g., us, gb, mx).
    • Structure: Language code comes first, followed by the country code, separated by a hyphen (e.g., en-us for English in the US, es-mx for Spanish in Mexico).
  • href="URL": Must be the absolute, fully-qualified URL (including https://) of the alternate page.

Key Implementation Rules (Bidirectional Linking)

  1. Self-Referencing Tag: Every page must include a hreflang tag that points to itself.
  2. Reciprocal Links: If Page A links to Page B with a hreflang tag, Page B must have a corresponding hreflang tag linking back to Page A. This creates a complete “cluster.”

The x-default Tag

Use the x-default value for the page you want search engines to show when no other language or regional version is a good match for the user’s browser settings or location. This is often a language-selection page or your main homepage.

HTML

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

2. Step-by-Step Implementation Methods

Google supports three ways to implement hreflang tags. You should only choose one method per page.

Method 1: HTML <head> Markup (Most Common)

This is the simplest method, suitable for smaller sites or sites where you have direct control over the page’s <head> section.

Action: Place all hreflang annotations within the <head> section of every corresponding page.

Example: For a blog post that has an English version (canonical: https://example.com/blog/article-a/) and a Spanish version (canonical: https://example.com/es/blog/articulo-a/), you would add the following tags to both URLs:

On the English Page (https://example.com/blog/article-a/):

HTML

<head>
  <link rel="alternate" hreflang="en" href="https://example.com/blog/article-a/" /> 
  <link rel="alternate" hreflang="es" href="https://example.com/es/blog/articulo-a/" /> 
  <link rel="alternate" hreflang="x-default" href="https://example.com/" />
</head>

On the Spanish Page (https://example.com/es/blog/articulo-a/):

HTML

<head>
  <link rel="alternate" hreflang="es" href="https://example.com/es/blog/articulo-a/" /> 
  <link rel="alternate" hreflang="en" href="https://example.com/blog/article-a/" /> 
  <link rel="alternate" hreflang="x-default" href="https://example.com/" />
</head>

Method 2: XML Sitemap (Best for Large Sites)

This method is ideal for websites with a very large number of pages or where CMS access to the <head> is difficult. It centralizes all hreflang data in one place.

Action: Update your existing XML Sitemap (or create a dedicated international one) to include the <xhtml:link> attribute within the <url> entry for each canonical page.

Example: Continuing with the English and Spanish pages:

XML

<?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/blog/article-a/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/blog/article-a/" />
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/blog/articulo-a/" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/" />
  </url>

  <url>
    <loc>https://example.com/es/blog/articulo-a/</loc>
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/blog/articulo-a/" />
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/blog/article-a/" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/" />
  </url>
</urlset>

Method 3: HTTP Headers (For Non-HTML Files)

This is primarily used for documents that don’t have an HTML <head> section, such as PDFs or other non-HTML documents.

Action: Implement hreflang via the HTTP header response of the server. This requires server-side configuration (e.g., in Apache or Nginx).

Example: For a PDF available in English (https://example.com/doc.pdf) and Spanish (https://example.com/es/doc.pdf):

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

(This header would be sent with the HTTP response for BOTH the English and Spanish PDF files.)

3. Technical Audit and Validation

Once implemented, validation is non-negotiable. Incorrect hreflang can be completely ignored by search engines, defeating the purpose.

  1. Use Google Search Console (GSC): Check the International Targeting report in GSC for any hreflang errors (e.g., missing return tags, invalid language codes).
  2. Third-Party Tools: Use tools like the Aleyda Solis hreflang Tag Generator or TechnicalSEO.com hreflang Tester to validate the code structure for individual URLs.
  3. Site Crawlers: Run a full crawl with tools like Screaming Frog to identify:
    • Missing self-references.
    • Missing reciprocal links (the most common error).
    • Invalid language/country codes.
    • References to non-canonical or broken URLs (4xx/5xx status codes).

By following these steps, you ensure that search engines can accurately identify and serve the correct language and regional content, significantly boosting your international performance.

Related Posts

Scroll to Top