You have spent months localizing your product into five languages. Your translated pages are live. But when you check Google Search Console, the Japanese version is barely getting impressions, the German page is cannibalizing your English one, and users in Brazil keep landing on the Spain-Spanish version.
The problem is almost always the same: hreflang tags are missing, broken, or misconfigured.
Hreflang is the mechanism that tells Google (and Yandex) which language and regional variant of a page to show to which users. It is a small piece of markup with outsized consequences for international SEO. When it works, the right users see the right pages. When it does not, your localization investment is partially wasted.
This guide covers everything you need to implement hreflang correctly — the syntax, the three implementation methods, the most common mistakes, and a step-by-step checklist. We will also show how we handle hreflang on the Alconost website across six locales.
What Are Hreflang Tags and Why Do They Matter
The hreflang attribute is an HTML annotation that tells search engines: "this page has equivalent versions in other languages or regions — here is which URL to serve for each." Google introduced it in 2011 to solve a specific problem: multilingual and multi-regional sites were getting penalized for duplicate content, even though the "duplicates" were legitimate translations.
Without hreflang, Google has to guess which version of your page to show. It uses signals like the user's IP address, browser language settings, and the page's own language. These guesses are often wrong — especially for content that looks structurally similar across languages (SaaS apps, e-commerce product pages, documentation).
Here is what hreflang solves:
Duplicate content across locales. Google may consolidate your /en/ and /de/ pages into a single canonical if it cannot tell they are intentional variants. Hreflang explicitly declares the relationship.
Wrong language in search results. A user in Tokyo searching in Japanese should see your /ja/ page, not your /en/ page. Hreflang ensures the correct version appears in SERPs for each locale.
Cannibalization between regional variants. If you have en-US and en-GB pages, they will compete with each other unless hreflang tells Google they target different regions.
Wasted crawl budget. When Google cannot understand your language structure, it may crawl and index the wrong versions, spending budget on pages that will not rank in the right markets.
The bottom line: hreflang does not directly boost rankings. What it does is ensure that the right page appears in the right market — which improves click-through rates, reduces bounce rates, and stops your own pages from competing with each other.
Hreflang Syntax: How to Write Correct Tags
There are three ways to implement hreflang. All three are functionally equivalent — Google treats them the same way. Choose based on your tech stack and the number of URLs you need to annotate.
Method 1: HTML <link> tags in the <head>
The most common approach. Add <link rel="alternate"> elements in the <head> of each page. Every language version of a page — including the page itself — must be listed.
<!-- On your English page: /en/pricing -->
<link rel="alternate" hreflang="en" href="https://example.com/en/pricing" />
<link rel="alternate" hreflang="de" href="https://example.com/de/pricing" />
<link rel="alternate" hreflang="ja" href="https://example.com/ja/pricing" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/pricing" />This same set of tags must appear on the /de/pricing and /ja/pricing pages as well. The tags must be bidirectional — if page A points to page B, page B must point back to page A.
Method 2: HTTP headers
Use this for non-HTML resources (PDFs, documents) or when you cannot modify the <head>. Add Link headers to the HTTP response:
Link: <https://example.com/en/pricing>; rel="alternate"; hreflang="en",
<https://example.com/de/pricing>; rel="alternate"; hreflang="de",
<https://example.com/ja/pricing>; rel="alternate"; hreflang="ja",
<https://example.com/en/pricing>; rel="alternate"; hreflang="x-default"Method 3: XML sitemap
Best for large sites with hundreds or thousands of localized URLs. Add xhtml:link elements inside each <url> entry in your sitemap:
<?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/en/pricing</loc>
<xhtml:link rel="alternate" hreflang="en"
href="https://example.com/en/pricing" />
<xhtml:link rel="alternate" hreflang="de"
href="https://example.com/de/pricing" />
<xhtml:link rel="alternate" hreflang="ja"
href="https://example.com/ja/pricing" />
<xhtml:link rel="alternate" hreflang="x-default"
href="https://example.com/en/pricing" />
</url>
<url>
<loc>https://example.com/de/pricing</loc>
<xhtml:link rel="alternate" hreflang="en"
href="https://example.com/en/pricing" />
<xhtml:link rel="alternate" hreflang="de"
href="https://example.com/de/pricing" />
<xhtml:link rel="alternate" hreflang="ja"
href="https://example.com/ja/pricing" />
<xhtml:link rel="alternate" hreflang="x-default"
href="https://example.com/en/pricing" />
</url>
</urlset>The sitemap method has one practical advantage: you can manage all hreflang relationships in a single file instead of editing every page. For sites with 50+ localized URLs, this is usually the cleanest approach.
Language and region codes
Hreflang values use ISO 639-1 language codes (2-letter), optionally combined with ISO 3166-1 Alpha-2 region codes. Some examples:
| Hreflang value | Meaning | When to use |
|---|---|---|
en | English (any region) | One English version for all regions |
en-US | English, United States | Separate US and UK English pages |
en-GB | English, United Kingdom | UK-specific spelling, pricing in GBP |
zh-CN | Chinese, mainland China | Simplified Chinese |
zh-TW | Chinese, Taiwan | Traditional Chinese |
pt-BR | Portuguese, Brazil | Brazilian Portuguese vs. European |
x-default | Fallback / language selector | Always include one |
Use language-only codes (like en, ja, ko) when you have a single version per language. Add the region code only when you have multiple regional variants of the same language — like en-US and en-GB, or zh-CN and zh-TW.
The most impactful thing you can do for multilingual SEO is get hreflang right. It is not glamorous work — it is plumbing. But when your Japanese page shows up for Japanese queries instead of being buried behind the English version, the traffic difference is immediate and measurable.
Common Hreflang Mistakes (and How to Fix Them)
Hreflang is conceptually simple but easy to break. Here are the mistakes we see most often when auditing multilingual websites — and how to fix each one.
1. Missing self-referencing tags
Every page must include a hreflang tag that points to itself. This is the single most common mistake. If your English page lists the German and Japanese versions but does not list itself, Google may ignore the entire hreflang set for that page.
<!-- WRONG: missing self-reference on /en/pricing -->
<link rel="alternate" hreflang="de" href="https://example.com/de/pricing" />
<link rel="alternate" hreflang="ja" href="https://example.com/ja/pricing" />
<!-- CORRECT: includes self-reference -->
<link rel="alternate" hreflang="en" href="https://example.com/en/pricing" />
<link rel="alternate" hreflang="de" href="https://example.com/de/pricing" />
<link rel="alternate" hreflang="ja" href="https://example.com/ja/pricing" />2. Broken return links (non-bidirectional)
Hreflang must be reciprocal. If page A declares page B as its German alternate, page B must declare page A as its English alternate. If the return link is missing, Google treats the annotation as invalid.
This often happens when a new locale is added to some pages but not others, or when a CMS generates hreflang tags on the source page but not on the translated versions.
3. Inconsistent URLs
The URL in your hreflang tag must exactly match the canonical URL of the target page. Common mismatches include:
Mixing
http://andhttps://Including or omitting trailing slashes inconsistently
Using
www.in hreflang but not in the canonical, or vice versaPointing to a URL that 301-redirects to a different URL
<!-- WRONG: hreflang points to non-canonical URL -->
<link rel="alternate" hreflang="de" href="http://www.example.com/de/pricing" />
<!-- ...but the canonical is: https://example.com/de/pricing -->
<!-- CORRECT: matches the canonical exactly -->
<link rel="alternate" hreflang="de" href="https://example.com/de/pricing" />4. Confusing language and country codes
The hreflang value is not a country code. hreflang="uk" means Ukrainian, not United Kingdom. hreflang="jp" is invalid — Japanese is ja. Some common traps:
| Wrong | Correct | Why |
|---|---|---|
jp | ja | JP is the country code; JA is the language code |
uk | en-GB | UK = Ukrainian language; use en-GB for British English |
cn | zh-CN | CN alone is not valid; language must come first |
br | pt-BR | BR is the region; Portuguese is the language |
5. Missing x-default
The x-default tag tells Google what to show when none of your other hreflang values match the user's locale. Without it, Google picks one on its own — and it may pick wrong. Always include an x-default that points to either your primary language version or a language-selection page.
6. Hreflang on non-indexable pages
If a page has a noindex meta tag, is blocked by robots.txt, or canonicalizes to a different URL, Google will ignore its hreflang tags. Make sure every page referenced in your hreflang set is indexable and self-canonical.
Hreflang Implementation Checklist
Use this checklist when setting up or auditing hreflang tags on your site. Each step is non-negotiable — skip one and the whole system can break.
- Audit your URL structure. Map every page to its language/region variants. Know exactly which pages exist in which locales before writing any tags.
- Choose your implementation method. HTML
<link>tags for small sites, XML sitemap for large ones, HTTP headers for non-HTML files. Pick one method per page — do not mix. - Use correct language codes. ISO 639-1 for language (
en,ja,ko), optionally combined with ISO 3166-1 for region (en-US,zh-CN). Do not invent codes. - Include self-referencing tags. Every page must list itself in its own hreflang set. This is mandatory.
- Ensure bidirectional links. If page A points to page B, page B must point back to page A. Validate every pair.
- Add x-default. Point it to your primary language version or language-selector page. One x-default per page set.
- Match hreflang URLs to canonicals. The URL in each hreflang tag must exactly match the canonical URL of that page — same protocol, same domain, same trailing slash.
- Verify all target pages are indexable. No
noindex, norobots.txtblocks, no cross-domain canonicals on any page in your hreflang set. - Test with Google Search Console. Check the International Targeting report for hreflang errors after deployment. Fix any "no return tag" or "unknown language code" warnings.
- Crawl with an SEO tool. Use Screaming Frog, Ahrefs, or Sitebulb to validate hreflang at scale. Manual checks work for 10 pages — not for 500.
- Monitor after launch. Hreflang tags can break when pages are added, removed, or restructured. Set up periodic crawls to catch regressions.
How We Implement Hreflang at Alconost
The Alconost website serves six locales: en, ja, ko, ru, zh-cn (Simplified Chinese), and zh-tw (Traditional Chinese). Here is how we handle hreflang across them — and what we learned along the way.
Our setup
We use Astro as our static site generator. Each locale has its own subdirectory (/en/, /ja/, /ko/, etc.), and hreflang tags are generated at build time based on a shared configuration that maps each page to its available language variants. The tags are injected into the <head> of every page.
A simplified version of what our output looks like:
<!-- On https://alconost.com/en/localization -->
<link rel="alternate" hreflang="en" href="https://alconost.com/en/localization" />
<link rel="alternate" hreflang="ja" href="https://alconost.com/ja/localization" />
<link rel="alternate" hreflang="ko" href="https://alconost.com/ko/localization" />
<link rel="alternate" hreflang="ru" href="https://alconost.com/ru/localization" />
<link rel="alternate" hreflang="zh-CN" href="https://alconost.com/zh-cn/localization" />
<link rel="alternate" hreflang="zh-TW" href="https://alconost.com/zh-tw/localization" />
<link rel="alternate" hreflang="x-default" href="https://alconost.com/en/localization" />What we learned
Not every page exists in every locale. Some blog posts are English-only. Some service pages are only in 4 of 6 languages. We had to build the hreflang set dynamically — only including locales where the page actually exists. Pointing hreflang to a 404 is worse than omitting the tag entirely.
zh-CN vs. zh-TW requires attention. Chinese Simplified and Traditional are different enough that Google treats them as separate locales, but similar enough that without hreflang, Google may consolidate them. We use
zh-CNandzh-TWas hreflang values, mapping to our/zh-cn/and/zh-tw/URL paths.Trailing slashes caused silent failures. Early on, some of our hreflang URLs included trailing slashes while the canonical URLs did not. Google silently ignored the mismatched tags — no error in Search Console, just missing hreflang annotations in the index. We caught it only when checking the cached page headers directly.
Build-time generation prevents drift. Because our hreflang tags are generated from a single source of truth at build time, they stay in sync automatically. CMS-based sites that generate hreflang per page at runtime are more prone to inconsistencies — especially when content editors add or remove language versions.
If you are building a multilingual site and want to get both the localization and the technical SEO right from the start, we can help. We have been doing this for 3,200+ projects — and yes, we set up hreflang on every one that needed it.
Frequently Asked Questions About Hreflang
Do hreflang tags affect rankings?
What is x-default in hreflang?
x-default value tells search engines which page to show when no other hreflang tag matches the user's language or region. It typically points to your primary language version or a language-selector page. Think of it as the fallback — if someone searches from a locale you haven't explicitly targeted, Google will serve the x-default URL instead of guessing. Do I need hreflang if I use subdirectories?
/en/, /ja/, or /ko/ gives Google a structural hint, but it is not a substitute for hreflang tags. Without hreflang, Google may still show the wrong language version in search results, especially for pages with similar content across locales. Hreflang tags explicitly declare the relationship between your language versions — subdirectories alone do not do that. How do I test hreflang tags?
<head> section of each page to confirm self-referencing tags and return links are present; (4) Hreflang Tags Testing Tool by Merkle — paste a URL and get instant validation of all hreflang attributes. Can I use hreflang with hyphens, like zh-Hans-CN?
zh-CN or en-GB. However, Google does not support script subtags like zh-Hans or zh-Hant. For Simplified Chinese targeting mainland China, use zh-CN. For Traditional Chinese targeting Taiwan, use zh-TW. 
