hreflang Implementation Guide: Language Tags, Formats, and Common Errors
The hreflang attribute uses ISO 639-1 two-letter language codes combined with optional ISO 3166-1 Alpha-2 country codes in a language-region format (like en-us or de-at). Over 65% of international websites have significant hreflang errors according to industry research, making proper implementation critical for international SEO success. The attribute tells search engines which language and regional version of a page to serve to users based on their location and language preferences.
This guide covers hreflang syntax, implementation methods, x-default usage, common errors, and validation strategies.
hreflang Quick Reference
| Component | Format | Example | Standard |
|---|---|---|---|
| Language code | 2 lowercase letters | en, de, fr, es | ISO 639-1 |
| Country code | 2 lowercase letters | us, gb, de, mx | ISO 3166-1 Alpha-2 |
| Combined format | language-country | en-us, de-at, fr-ca | Combined |
| Global fallback | x-default | x-default | Special value |
Common Language-Region Combinations
| hreflang Value | Target Audience |
|---|---|
| en-us | English speakers in the United States |
| en-gb | English speakers in the United Kingdom |
| en-au | English speakers in Australia |
| de-de | German speakers in Germany |
| de-at | German speakers in Austria |
| de-ch | German speakers in Switzerland |
| fr-fr | French speakers in France |
| fr-ca | French speakers in Canada |
| es-es | Spanish speakers in Spain |
| es-mx | Spanish speakers in Mexico |
| pt-br | Portuguese speakers in Brazil |
| pt-pt | Portuguese speakers in Portugal |
| zh-cn | Chinese (Simplified) for China |
| zh-tw | Chinese (Traditional) for Taiwan |
What Is hreflang and Why Does It Matter?
The hreflang attribute is an HTML attribute that tells search engines about the language and geographic targeting of your web pages. Google introduced hreflang in 2011 to help websites with multilingual or multi-regional content serve the correct version to users.
Primary Purposes
Language targeting: Show French content to French-speaking users and German content to German-speaking users, regardless of their location.
Regional targeting: Show different versions of the same language to users in different countries. A US user and a UK user both speak English, but may see different content with localized spelling, currency, or products.
Duplicate content signals: Tell search engines that similar pages in different languages are intentional variants, not duplicates. Without hreflang, search engines may view your English and American English pages as duplicate content.
When to Use hreflang
Use hreflang when you have:
- The same content translated into multiple languages
- Regional variations of the same language (en-us vs en-gb)
- Country-specific pages with different products, prices, or regulations
- A global website with multiple language/region combinations
You do not need hreflang for:
- A single-language website
- Pages that are not localized (like a blog only in English)
- User-generated content in different languages on the same page
hreflang Format and Syntax Rules
Understanding the exact syntax is critical because hreflang errors often come from incorrect formatting. Search engines are strict about hreflang syntax and will ignore improperly formatted tags.
Language Codes (ISO 639-1)
The language code must be a two-letter lowercase code from the ISO 639-1 standard.
| Language | Code | Language | Code |
|---|---|---|---|
| English | en | Japanese | ja |
| Spanish | es | Korean | ko |
| French | fr | Russian | ru |
| German | de | Arabic | ar |
| Portuguese | pt | Hindi | hi |
| Italian | it | Dutch | nl |
| Chinese | zh | Polish | pl |
Country Codes (ISO 3166-1 Alpha-2)
The optional country code must be a two-letter lowercase code from the ISO 3166-1 Alpha-2 standard.
| Country | Code | Country | Code |
|---|---|---|---|
| United States | us | Australia | au |
| United Kingdom | gb | Canada | ca |
| Germany | de | Mexico | mx |
| France | fr | Brazil | br |
| Spain | es | Japan | jp |
| Italy | it | South Korea | kr |
| Netherlands | nl | India | in |
| Switzerland | ch | China | cn |
Syntax Rules
Language-only: Use just the language code when the content is the same for all speakers of that language.
hreflang="de"
Language-region: Combine language and country with a hyphen when you have regional variations.
hreflang="de-at"
Case sensitivity: Use lowercase for both codes. While some browsers may tolerate uppercase, lowercase is the standard.
Separator: Use a hyphen (-), never an underscore (_) or space.
// Correct
hreflang="en-us"
hreflang="de-at"
// Incorrect
hreflang="en_us"
hreflang="EN-US"
hreflang="en US"
Language vs. Region Priority
Language code only (de): Targets all German speakers globally. Use when you have one German page for all German-speaking countries.
Language-region code (de-at): Targets German speakers specifically in Austria. Use when you have separate pages for Germany, Austria, and Switzerland.
Important: You can use language-only and language-region codes together. For example:
- de-de for Germany
- de-at for Austria
- de-ch for Switzerland
- de as a catch-all for other German-speaking users
Three Implementation Methods
You must choose ONE implementation method and use it consistently across your entire site. Mixing methods can cause conflicts and errors.
Method 1: HTML Link Elements (Head Section)
Place hreflang link elements in the <head> section of each page. This is the most common method for websites with a moderate number of language versions.
Syntax:
<link rel="alternate" hreflang="language-code" href="absolute-url" />
Complete example:
<head>
<link rel="alternate" hreflang="en-us" href="https://example.com/page/" />
<link rel="alternate" hreflang="en-gb" href="https://example.com/uk/page/" />
<link rel="alternate" hreflang="de-de" href="https://example.com/de/page/" />
<link rel="alternate" hreflang="fr-fr" href="https://example.com/fr/page/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page/" />
</head>
Best for:
- Small to medium websites (under 50 language/region combinations)
- Sites without access to server configuration
- CMS-based websites where you control the head section
Considerations:
- Increases HTML page size
- Must be added to every page
- Easier to audit in browser dev tools
Method 2: HTTP Headers
Use HTTP response headers for non-HTML files like PDFs, or when you cannot modify the HTML. The server sends hreflang information in the HTTP response.
Syntax:
Link: <url>; rel="alternate"; hreflang="language-code"
Complete example:
HTTP/1.1 200 OK
Link: <https://example.com/doc.pdf>; rel="alternate"; hreflang="en-us",
<https://example.com/uk/doc.pdf>; rel="alternate"; hreflang="en-gb",
<https://example.com/de/doc.pdf>; rel="alternate"; hreflang="de-de",
<https://example.com/doc.pdf>; rel="alternate"; hreflang="x-default"
Apache .htaccess example:
<Files "document.pdf">
Header add Link "<https://example.com/document.pdf>; rel=\"alternate\"; hreflang=\"en-us\""
Header add Link "<https://example.com/de/document.pdf>; rel=\"alternate\"; hreflang=\"de-de\""
</Files>
Nginx configuration example:
location /document.pdf {
add_header Link '<https://example.com/document.pdf>; rel="alternate"; hreflang="en-us"';
add_header Link '<https://example.com/de/document.pdf>; rel="alternate"; hreflang="de-de"';
}
Best for:
- PDF files and other non-HTML content
- Sites with server access but no HTML control
- CDN-delivered content
Considerations:
- Requires server configuration access
- Cannot be seen in page source
- More complex to audit
Method 3: XML Sitemap
Add hreflang annotations to your XML sitemap. This is the recommended method for large websites with many language versions.
Syntax:
<url>
<loc>page-url</loc>
<xhtml:link rel="alternate" hreflang="language-code" href="alternate-url" />
</url>
Complete example:
<?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/page/</loc>
<xhtml:link rel="alternate" hreflang="en-us" href="https://example.com/page/" />
<xhtml:link rel="alternate" hreflang="en-gb" href="https://example.com/uk/page/" />
<xhtml:link rel="alternate" hreflang="de-de" href="https://example.com/de/page/" />
<xhtml:link rel="alternate" hreflang="fr-fr" href="https://example.com/fr/page/" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page/" />
</url>
<url>
<loc>https://example.com/uk/page/</loc>
<xhtml:link rel="alternate" hreflang="en-us" href="https://example.com/page/" />
<xhtml:link rel="alternate" hreflang="en-gb" href="https://example.com/uk/page/" />
<xhtml:link rel="alternate" hreflang="de-de" href="https://example.com/de/page/" />
<xhtml:link rel="alternate" hreflang="fr-fr" href="https://example.com/fr/page/" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page/" />
</url>
<!-- Continue for all language versions -->
</urlset>
Best for:
- Large websites (50+ pages per language)
- Sites with many language/region combinations
- Dynamic websites where HTML modification is complex
- Centralized management of international SEO
Considerations:
- Must include ALL hreflang annotations for each URL
- Sitemap can become very large
- Easier to maintain programmatically
- Single source of truth for all hreflang data
Understanding x-default
The x-default value is a special hreflang value that designates your fallback or default page for users who do not match any of your specified language-region combinations.
When to Use x-default
Global landing page: Point x-default to a language selector page where users can choose their preferred version.
Primary language version: Point x-default to your main language version (often English) for users from countries you do not specifically target.
Geolocation redirect page: Point x-default to a page that automatically redirects users based on their detected location.
x-default Implementation
<head>
<link rel="alternate" hreflang="en-us" href="https://example.com/us/" />
<link rel="alternate" hreflang="en-gb" href="https://example.com/uk/" />
<link rel="alternate" hreflang="de-de" href="https://example.com/de/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />
</head>
x-default Best Practices
Always include x-default: It provides a safety net for users from locations you have not specifically targeted.
Choose strategically: Your x-default should be your most universal content version or a language selector page.
One x-default per page set: Each group of alternate pages should have exactly one x-default.
x-default Scenarios
| Scenario | x-default Points To |
|---|---|
| Language selector | Page with language/region options |
| US company | English US version |
| European company | International English version |
| Multiple regions | Generic language version |
Critical Requirements: Self-Referencing and Bidirectional Links
Two requirements cause the majority of hreflang errors. Missing either one will cause search engines to ignore your hreflang implementation.
Self-Referencing Tags (Required)
Every page MUST include a hreflang tag pointing to itself. This is not optional.
Example for the German page (https://example.com/de/page/):
<head>
<!-- Self-referencing tag - REQUIRED -->
<link rel="alternate" hreflang="de-de" href="https://example.com/de/page/" />
<!-- Other language versions -->
<link rel="alternate" hreflang="en-us" href="https://example.com/page/" />
<link rel="alternate" hreflang="fr-fr" href="https://example.com/fr/page/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page/" />
</head>
Why self-referencing is required:
- Confirms the page acknowledges its own language/region targeting
- Completes the bidirectional link chain
- Validates that the hreflang set is intentional
Bidirectional Return Links (Required)
Every page in your hreflang set must link to ALL other pages in the set, AND those pages must link back. This creates a complete bidirectional relationship.
Correct bidirectional implementation:
Page A (English US) must contain:
<link rel="alternate" hreflang="en-us" href="https://example.com/page/" />
<link rel="alternate" hreflang="de-de" href="https://example.com/de/page/" />
Page B (German) must contain:
<link rel="alternate" hreflang="en-us" href="https://example.com/page/" />
<link rel="alternate" hreflang="de-de" href="https://example.com/de/page/" />
Both pages must have identical hreflang sets. If Page A points to Page B but Page B does not point back to Page A, the hreflang relationship is broken.
Common Bidirectional Errors
Missing return link:
Page A -> Page B (OK)
Page B -> (no link to Page A) (ERROR)
Mismatched URLs:
Page A links to: https://example.com/de/page/
Page B self-references: https://example.com/de/page (no trailing slash)
Incomplete sets:
Page A lists: en-us, de-de, fr-fr
Page B lists: en-us, de-de (missing fr-fr)
Common hreflang Errors and Solutions
Research shows over 65% of international websites have significant hreflang errors. Here are the most common mistakes and how to fix them.
Error 1: Missing Self-Referencing Tags
Problem: Page does not include an hreflang tag pointing to itself.
Impact: Search engines may ignore all hreflang tags on the page.
Solution: Always include a self-referencing hreflang tag.
<!-- On https://example.com/de/page/ -->
<!-- Missing: self-reference -->
<link rel="alternate" hreflang="en-us" href="https://example.com/page/" />
<!-- Correct -->
<link rel="alternate" hreflang="de-de" href="https://example.com/de/page/" />
<link rel="alternate" hreflang="en-us" href="https://example.com/page/" />
Error 2: Broken Return Links
Problem: Page A links to Page B, but Page B does not link back to Page A.
Impact: The hreflang relationship is invalid and ignored.
Solution: Ensure every page in the hreflang set links to all other pages.
Error 3: Invalid Language or Country Codes
Problem: Using incorrect codes like “uk” for Ukraine (should be “ua”) or “en-UK” (should be “en-gb”).
Common mistakes:
- uk instead of gb for United Kingdom
- jp instead of ja for Japanese language
- chi instead of zh for Chinese
Solution: Always verify codes against ISO 639-1 (language) and ISO 3166-1 Alpha-2 (country) standards.
Error 4: URL Mismatches
Problem: URLs in hreflang tags do not exactly match the actual page URLs.
Common issues:
- http vs https
- www vs non-www
- Trailing slash vs no trailing slash
- Query parameters included/excluded
Solution: Use canonical URLs consistently across all hreflang tags.
<!-- All URLs must match exactly -->
<link rel="alternate" hreflang="en-us" href="https://www.example.com/page/" />
<!-- Not: http://example.com/page or https://www.example.com/page (no slash) -->
Error 5: Pointing to Non-Canonical URLs
Problem: hreflang tags point to URLs that redirect or have different canonical tags.
Impact: Conflicting signals confuse search engines.
Solution: hreflang URLs should match the canonical URL of each page.
Error 6: Mixing Implementation Methods
Problem: Using HTML link elements on some pages and sitemap annotations on others.
Impact: Conflicting or incomplete hreflang signals.
Solution: Choose ONE implementation method and use it consistently across your entire site.
Error 7: Wrong Country Code Format
Problem: Using three-letter country codes (ISO 3166-1 Alpha-3) instead of two-letter codes (Alpha-2).
<!-- Wrong -->
<link rel="alternate" hreflang="en-usa" href="..." />
<!-- Correct -->
<link rel="alternate" hreflang="en-us" href="..." />
Error 8: Uppercase Codes
Problem: Using uppercase letters in language or country codes.
<!-- Wrong -->
<link rel="alternate" hreflang="EN-US" href="..." />
<!-- Correct -->
<link rel="alternate" hreflang="en-us" href="..." />
hreflang Validation and Testing
Regular validation is essential because hreflang errors are silent. Search engines will not warn you when they ignore your hreflang tags.
Google Search Console
International Targeting report:
- Navigate to Legacy tools > International Targeting
- Shows hreflang tag errors detected by Google
- Lists pages with issues
Coverage report:
- Check for pages excluded due to “Alternate page with proper canonical tag”
- May indicate hreflang/canonical conflicts
Manual Validation Checklist
For each page in your hreflang set, verify:
- Self-referencing tag exists
- All alternate pages are listed
- All URLs are correct and absolute
- Language and country codes are valid
- x-default is included
- URLs match canonical URLs
Automated Validation Tools
Screaming Frog SEO Spider:
- Crawls entire site
- Reports hreflang errors
- Identifies missing return links
Ahrefs Site Audit:
- Detects hreflang issues
- Shows missing or conflicting tags
Merkle hreflang Tag Testing Tool:
- Free online validator
- Tests individual pages
- Shows bidirectional link status
Testing Process
Step 1: Validate syntax
- Check language codes against ISO 639-1
- Check country codes against ISO 3166-1 Alpha-2
- Verify hyphen separator (not underscore)
- Confirm lowercase format
Step 2: Verify completeness
- Self-referencing tag present
- All language versions included
- x-default specified
Step 3: Check bidirectional links
- Visit each alternate page
- Verify it links back to all other versions
- Confirm URLs match exactly
Step 4: Monitor Search Console
- Check International Targeting report
- Review any hreflang errors
- Verify correct pages appear in target regions
hreflang and Other SEO Elements
hreflang works alongside other SEO elements. Understanding these relationships prevents conflicts.
hreflang and Canonical Tags
The canonical URL and hreflang URL should match. If a page has a canonical tag pointing to a different URL, hreflang signals become conflicting.
<!-- Correct: canonical matches self-referencing hreflang -->
<link rel="canonical" href="https://example.com/de/page/" />
<link rel="alternate" hreflang="de-de" href="https://example.com/de/page/" />
<!-- Incorrect: canonical and hreflang conflict -->
<link rel="canonical" href="https://example.com/page/" />
<link rel="alternate" hreflang="de-de" href="https://example.com/de/page/" />
hreflang and Redirects
Never point hreflang tags to URLs that redirect. hreflang URLs should return a 200 status code.
hreflang and Content
Pages in an hreflang set should have equivalent content. While the content is in different languages, it should cover the same topic. Do not use hreflang to link unrelated pages.
Frequently Asked Questions
What happens if I make hreflang errors?
Search engines will ignore invalid hreflang tags. Your pages will still be indexed, but users may see the wrong language version in search results. There is no penalty, but you lose the benefit of international targeting.
Can I use hreflang for the same language in different countries?
Yes, this is a common use case. Use hreflang=“en-us” for American English and hreflang=“en-gb” for British English. This helps show users content with their local spelling, currency, and product availability.
Should I use language-only or language-region codes?
Use language-only (de) when you have one version for all speakers of that language. Use language-region (de-at) when you have specific versions for different countries. You can combine both approaches.
How many hreflang tags is too many?
There is no strict limit, but consider the sitemap method if you have more than 20-30 language/region combinations. Large HTML head sections can slow page loading.
Does hreflang affect page ranking?
hreflang does not directly affect rankings. It influences which version of your page appears in search results based on the searcher’s location and language. Proper implementation can reduce bounce rates from language mismatches.
How long does it take for hreflang changes to take effect?
Search engines need to recrawl all pages in your hreflang set. This can take days to weeks depending on your site’s crawl frequency. Use Google Search Console to request recrawling of important pages.
Key Takeaways
- hreflang uses ISO 639-1 language codes (2 letters) and ISO 3166-1 Alpha-2 country codes combined as language-region (en-us, de-at)
- Self-referencing tags are REQUIRED on every page in the hreflang set
- Bidirectional return links between ALL language versions are REQUIRED
- Choose ONE implementation method (HTML head, HTTP headers, or XML sitemap) and use it consistently
- x-default designates your fallback page for users not matching any specific language-region
- Over 65% of international websites have significant hreflang errors, mostly from missing return links or syntax issues
- hreflang URLs must exactly match canonical URLs, including protocol, www, and trailing slashes
Conclusion
Proper hreflang implementation is essential for international SEO, ensuring search engines serve the correct language and regional version of your pages to users worldwide. The most common errors stem from missing self-referencing tags, broken bidirectional links, and inconsistent URL formats. Choose one implementation method, validate your tags regularly with Search Console and crawling tools, and ensure every page in your hreflang set maintains complete bidirectional relationships with all alternate versions. Try our free letter counter → to verify your hreflang tag content fits within your templates and character limits.