Table of Contents
Hreflang SEO: The Complete Guide to International Language Targeting
If your website serves users in multiple languages or regions, hreflang SEO is one of the most important — and most misunderstood — technical topics you need to master. Getting hreflang right means search engines serve the correct language version of your pages to the right users. Getting it wrong means lost traffic, duplicate content penalties, and frustrated visitors landing on pages they cannot read.
This hreflang guide covers everything: what hreflang is, how it works, all three implementation methods, common mistakes, and how to debug issues when they arise.
What Is Hreflang?
Understanding what is hreflang starts with the problem it solves. When you publish content in multiple languages — say, English, French, and German — search engines see multiple URLs with very similar content. Without signals, they may treat these as duplicate pages or, worse, show the wrong version to users searching in a particular language.
The hreflang attribute is an HTML signal that tells search engines like Google which language and, optionally, which regional variant a page targets. It also defines the relationship between all language variants of the same page, forming a self-referential set.
The hreflang meaning, stripped to its core, is this: "This page is in language X (and optionally for region Y), and here are the equivalent pages in other languages."
Google introduced support for hreflang in 2011. Yandex — the dominant search engine in Russia — also supports hreflang, though Yandex hreflang implementation has some nuances covered later in this guide. Bing does not officially support hreflang, but it does read the lang attribute on HTML elements.
Hreflang Attribute Syntax and Format
The hreflang attribute follows a specific syntax. Understanding the format is essential before you look at any example hreflang implementation.
Language Code Format
Hreflang values use IETF BCP 47 language tags:
- Language only:
en,fr,de,ja - Language + region:
en-US,en-GB,fr-FR,fr-CA,pt-BR,pt-PT - Special catch-all:
x-default
For hreflang english targeting, use en to target all English speakers regardless of region, or en-US / en-GB to distinguish American and British audiences. Using a language-only code casts a wider net; combining language and region lets you serve localised content (different spellings, currencies, or legal disclosures) to specific countries.
The x-default value is special. It designates a fallback page for users whose language or region does not match any specific variant — typically a language selector page or the most widely applicable version of your content.
The rel="alternate" hreflang Link Element
A single hreflang tag element looks like this:
<link rel="alternate" hreflang="en" href="https://example.com/page/" />
The rel="alternate" part signals an alternate version of the current page. The hreflang attribute specifies the language (and optionally region). The href attribute provides the canonical URL of that alternate version.
The full phrase link rel alternate hreflang describes the complete element: a link element with rel="alternate" and an hreflang attribute. You will also encounter this written as rel alternate hreflang or link alternate hreflang in documentation — all refer to the same element.
Three Implementation Methods
There are three valid ways to implement hreflang. Each has appropriate use cases. The method you choose depends on your tech stack and site architecture.
Method 1: HTML Head Implementation
The most common approach is placing hreflang link elements inside the <head> of each HTML page. This is what most developers mean when they say "where to put hreflang tags" — and the answer is: in the <head>.
Here is a complete hreflang tag example for a page available in three language variants:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>About Us</title>
<!-- hreflang self-reference (required) -->
<link rel="alternate" hreflang="en" href="https://example.com/about/" />
<!-- alternate language variants -->
<link rel="alternate" hreflang="fr" href="https://example.com/fr/about/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/about/" />
<!-- x-default fallback -->
<link rel="alternate" hreflang="x-default" href="https://example.com/about/" />
</head>
<body>
<!-- page content -->
</body>
</html>
Key points for HTML head implementation:
- Every page in the set must include hreflang links for all variants in the set, including itself.
- The self-referencing link (pointing back to the current page) is required.
- URLs must be absolute — relative URLs are not valid in hreflang.
- Include
x-defaultwhen you have a language-neutral fallback or selector page.
The hreflang and lang attributes relationship is worth clarifying here. The lang attribute on the <html> element (<html lang="en">) tells browsers and assistive technologies the language of the page content. The hreflang attribute in <link> elements tells search engines about alternate versions. Both serve different audiences (browsers vs. crawlers) and should be consistent with each other, but they are distinct mechanisms.
Similarly, meta hreflang is not a real element — there is no <meta> tag for hreflang. The correct element is always <link rel="alternate" hreflang="..." href="..." />. You may also see references to href language tags, which is just an informal way of describing the same hreflang link elements.
Method 2: HTTP Headers
For non-HTML resources — PDFs, XML files, or dynamically served documents — you cannot embed HTML tags. In these cases, you can signal hreflang via HTTP response headers.
Link: <https://example.com/document.pdf>; rel="alternate"; hreflang="en",
<https://example.com/fr/document.pdf>; rel="alternate"; hreflang="fr",
<https://example.com/de/document.pdf>; rel="alternate"; hreflang="de"
This is particularly useful for PDF-heavy sites (legal documents, whitepapers) where you maintain translated versions of downloadable files. The syntax mirrors the HTML approach but uses the HTTP Link header instead.
Configuration in Apache (.htaccess):
<Files "document.pdf">
Header add Link '<https://example.com/document.pdf>; rel="alternate"; hreflang="en"'
Header add Link '<https://example.com/fr/document.pdf>; rel="alternate"; hreflang="fr"'
</Files>
Method 3: XML Sitemap
The XML sitemap method is often the most practical for large sites because it centralises all hreflang declarations in one place. Instead of modifying every HTML page, you define the hreflang relationships in your sitemap file.
This is the recommended answer to "how to add hreflang tags" for sites with hundreds or thousands of pages.
<?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">
<!-- English version -->
<url>
<loc>https://example.com/about/</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/about/" />
<xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/about/" />
<xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/about/" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/about/" />
</url>
<!-- French version -->
<url>
<loc>https://example.com/fr/about/</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/about/" />
<xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/about/" />
<xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/about/" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/about/" />
</url>
<!-- German version -->
<url>
<loc>https://example.com/de/about/</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/about/" />
<xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/about/" />
<xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/about/" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/about/" />
</url>
</urlset>
Each <url> block represents one page URL and must contain <xhtml:link> elements for every variant — including itself. Google requires the xmlns:xhtml namespace declaration on the <urlset> element.
Yandex Hreflang Considerations
Yandex hreflang support is similar to Google's but has some differences worth noting. Yandex uses hreflang to understand language targeting, but it places stronger emphasis on the geotargeting settings configured in Yandex Webmaster. If you are targeting Russian-speaking audiences in different countries (Russia, Ukraine, Kazakhstan), combine hreflang with explicit country targeting in Yandex Webmaster for best results.
Yandex also processes hreflang from both HTML head tags and XML sitemaps. However, Yandex is more reliant on the lang attribute and Content-Language HTTP headers as additional signals. When optimising for Yandex alongside Google, ensure your hreflang values, lang attributes, and server headers are all consistent.
How to Set Hreflang: A Step-by-Step Process
Understanding how to set hreflang correctly requires thinking about your entire site structure before writing a single tag.
Step 1: Map Your Language Variants
List every URL and its corresponding translations. For each page that exists in multiple languages, record the full absolute URL for each variant.
Step 2: Choose Your Language Codes
Use ISO 639-1 two-letter language codes (en, fr, de, ja, zh). For regional variants, append an ISO 3166-1 alpha-2 country code (en-US, en-AU, zh-TW, zh-CN). Avoid three-letter codes or non-standard tags — Google and Yandex will ignore invalid values.
Step 3: Decide on x-default
Determine whether you need an x-default page. If you have a language selector landing page or one variant that should catch all unmatched users, designate it with x-default.
Step 4: Choose Your Implementation Method
- Use HTML head tags for server-rendered HTML sites where you can modify the
<head>template. - Use XML sitemap for large sites or static site generators where modifying every page individually is impractical.
- Use HTTP headers for non-HTML resources.
Step 5: Implement and Validate
After implementation, validate using Google Search Console and third-party tools. Check that every page in a set references all other pages in the set, including itself.
Hreflang Usage Patterns
Understanding correct hreflang usage means understanding when to use language-only codes versus language-region codes.
Language only (en): Use when you have a single English version and do not need to differentiate by region. This targets all English speakers globally.
Language + region (en-US, en-GB): Use when you maintain separate content for distinct regional audiences — for example, separate pages for American and British English with localised pricing, spelling, or legal content.
Avoid mixing: Do not use both en and en-US for overlapping audiences in the same hreflang set. If you use regional codes, use them consistently. Mixing language-only and language-region codes for the same audience confuses search engines.
How to use hreflang for a site with regional English variants:
<!-- For the US English page -->
<link rel="alternate" hreflang="en-US" href="https://example.com/us/pricing/" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/pricing/" />
<link rel="alternate" hreflang="en-AU" href="https://example.com/au/pricing/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/pricing/" />
Hreflang links must always be bidirectional. If Page A in English declares Page B in French as its alternate, Page B in French must declare Page A in English as its alternate. One-directional hreflang links are one of the most common errors.
Common Hreflang Mistakes
Even experienced developers make mistakes with hreflang implementation. Here are the errors that appear most frequently.
Missing Self-Reference
Every page must include a hreflang link pointing to itself. Omitting the self-reference is invalid and causes Google to ignore the entire set.
<!-- WRONG: Missing self-reference on the English page -->
<link rel="alternate" hreflang="fr" href="https://example.com/fr/about/" />
<!-- CORRECT: Include self-reference -->
<link rel="alternate" hreflang="en" href="https://example.com/about/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/about/" />
Non-Bidirectional Tags
If the French page does not reciprocate the English page's hreflang declaration, Google will not trust the signal. Every page in a set must declare all other pages in the set.
Using Relative URLs
Hreflang href values must be absolute URLs including protocol and domain. Using relative paths like /about/ instead of https://example.com/about/ will cause the implementation to fail silently.
Invalid Language Codes
Using codes like en-uk (lowercase country code), eng (three-letter code), or made-up region codes will cause Google and Yandex to ignore those tags. Always use valid BCP 47 tags with uppercase country codes: en-GB, not en-gb or en-uk.
Hreflang on Non-Canonical URLs
Apply hreflang only to canonical URLs. If you have paginated pages or URL parameters creating duplicate URLs, do not add hreflang to non-canonical variants. Always point hreflang to the same URL you designate as canonical.
Inconsistent Sets Across Pages
All pages in a hreflang set must reference the same complete list of variants. If you add a new language variant but only update half the pages, the incomplete set will cause inconsistent signals.
Hreflang Best Practices
Following established hreflang best practices saves significant debugging time.
Centralise management. Use XML sitemaps or a CMS-level automation to generate hreflang tags programmatically. Manual management at scale is error-prone.
Use absolute URLs consistently. Include protocol, subdomain (if applicable), and trailing slash (or no trailing slash, consistently) in every href value.
Validate before deploying. Use Google's Rich Results Test, Screaming Frog (which has dedicated hreflang auditing), or hreflang.es to check your implementation before it goes live.
Keep sets complete. When adding a new language, update every page in the set — not just the new language's pages.
Audit regularly. Pages get added, removed, and restructured. Schedule periodic hreflang audits (quarterly at minimum) to catch broken links or missing declarations.
Combine with canonical tags. Hreflang and canonical tags work together. The canonical tag handles duplicate content on a per-language basis; hreflang handles cross-language relationships. Use both.
Monitor in Google Search Console. The International Targeting report in Search Console surfaces hreflang errors including missing return tags, invalid language codes, and unreachable URLs.
Hreflang and Lang Attributes: Understanding the Difference
A point of frequent confusion is the relationship between hreflang and lang attributes. They are not interchangeable.
| Attribute | Where | Purpose | Audience |
|---|---|---|---|
lang on <html> | HTML element | Declares page language to browsers and screen readers | Browsers, assistive tech |
hreflang on <link> | HTML <head> or sitemap | Signals alternate language versions to search engines | Search engine crawlers |
The lang attribute (<html lang="fr">) is an accessibility and browser feature. It affects how browsers render quotes, hyphenation, and how screen readers pronounce content. It does not directly influence search engine language targeting.
Hreflang implementation, by contrast, is purely for search engines. Always set both consistently: a French page should have <html lang="fr"> and hreflang links that include hreflang="fr" pointing to itself.
The balise hreflang (French for "hreflang tag") refers to the same <link rel="alternate" hreflang="..."> element — the term appears in French-language SEO documentation and refers to identical technical implementation.
Debugging Hreflang Issues
When your hreflang implementation is not working as expected, use a systematic debugging approach.
Check Google Search Console
Navigate to Search Console > International Targeting > Language. This report shows detected hreflang tags and errors. Common errors reported:
- No return tags: Page A references Page B but Page B does not reference Page A.
- Unknown language tag: Invalid BCP 47 language code used.
- URL not indexed: Hreflang target URL returns non-200 status or is blocked by robots.txt.
Crawl with Screaming Frog
Screaming Frog's hreflang tab shows every hreflang annotation found during a crawl, highlights mismatches, missing self-references, and non-canonical URLs in hreflang. For sites with hundreds of pages, this is the most efficient audit method.
Inspect HTTP Headers
For HTTP header implementation, verify the Link headers are being sent correctly:
curl -I https://example.com/document.pdf
Look for Link: headers in the response. If they are absent, the server configuration needs review.
Validate Language Codes
Use the IANA Language Subtag Registry to verify every language code used in your implementation. Any code not in this registry is invalid and will be ignored.
Check Sitemap Submission
If using the XML sitemap method, confirm the sitemap is submitted and indexed in Search Console. An unsubmitted or blocked sitemap means Google may not read your hreflang declarations.
Automating Hreflang Tag Generation with better-i18n
Manual hreflang management becomes unsustainable as your site grows. Adding a new language means updating every page across all language variants. Restructuring URLs means updating hreflang references everywhere. Missing a single page breaks the entire set for that URL.
better-i18n automates hreflang tag generation for multilingual sites. When you add a new locale or publish a new page, better-i18n automatically generates the correct, complete, bidirectional hreflang link elements across your entire site. No manual audits, no missing self-references, no incomplete sets.
For teams managing i18n at scale — whether through a headless CMS, a framework like Next.js or Nuxt, or a custom content pipeline — better-i18n handles the implementation details so your developers focus on content and features rather than hreflang bookkeeping.
Key capabilities relevant to hreflang SEO:
- Automatic generation of
<link rel="alternate" hreflang="...">tags for every page and locale. - Support for HTML head, sitemap, and HTTP header injection methods.
- Validation of language codes against BCP 47 standards.
- Detection and alerting for incomplete hreflang sets when a translation is missing.
- Integration with CI/CD pipelines to catch hreflang regressions before deployment.
If you are building or scaling a multilingual site, automating hreflang implementation from the start prevents the accumulated technical debt that comes with manual management.
Summary
Hreflang SEO is foundational for any website targeting users across multiple languages or regions. The hreflang tag — implemented via <link rel="alternate" hreflang="..."> in the HTML head, via HTTP headers, or via XML sitemaps — tells search engines which language variant to serve to which users.
Getting hreflang implementation right requires:
- Valid BCP 47 language codes (e.g.,
en,en-US,fr-FR) - Complete, bidirectional sets (every page references all variants including itself)
- Absolute URLs in every
hrefvalue - Consistency between hreflang, canonical tags, and
langattributes - Regular auditing via Google Search Console and crawler tools
The most common source of hreflang problems is scale: maintaining correct tags manually across hundreds of pages in multiple languages is error-prone. Tools like better-i18n eliminate this problem by generating and validating hreflang tags automatically, keeping your international SEO foundation solid as your site grows.
Whether you are just learning how to add hreflang tags to your first multilingual site or debugging a complex hreflang set across thousands of URLs, the principles remain the same: accurate language targeting, complete bidirectional references, and consistent, validated implementation.
