Hreflang is the most commonly broken piece of technical SEO, and the reason is specific. It is the only annotation Google will discard entirely if one part of the set is wrong. Get a single return link missing and the whole cluster is ignored, silently, with no error anywhere you would normally look.
This guide covers what hreflang does, the exact syntax, the five failures that account for almost every broken implementation, and how to verify yours actually works.
What hreflang actually does
Hreflang tells Google which language or country version of a page to show a given user. That is all it does.
It is worth stating what it does not do, because the misunderstanding is expensive:
- It is not a ranking signal. Correct hreflang will not move you up. Incorrect hreflang will cost you by serving the wrong page.
- It does not consolidate authority. Your market versions still rank on their own merits.
- It does not stop indexing. Every version still gets indexed separately.
- It is a hint, not a directive. Google treats it as a strong signal, not a command.
The job it does well is preventing your own versions from competing. Without it, an English Singapore page and an English Malaysia page targeting the same terms look like duplicates, and Google picks one, often the wrong one.
The syntax
Three implementation methods exist. Pick one and use it consistently.
In the HTML head, the most common:
<link rel=“alternate” hreflang=“en-sg” href=“https://brand.com/sg/” />
<link rel=“alternate” hreflang=“en-my” href=“https://brand.com/my/” />
<link rel=“alternate” hreflang=“ja-jp” href=“https://brand.com/jp/” />
<link rel=“alternate” hreflang=“x-default” href=“https://brand.com/” />
In the XML sitemap, better for large sites because you edit one file instead of thousands of templates:
<url>
<loc>https://brand.com/sg/</loc>
<xhtml:link rel=“alternate” hreflang=“en-sg” href=“https://brand.com/sg/”/>
<xhtml:link rel=“alternate” hreflang=“en-my” href=“https://brand.com/my/”/>
<xhtml:link rel=“alternate” hreflang=“x-default” href=“https://brand.com/”/>
</url>
In the HTTP header, used for non-HTML files such as PDFs.
Do not mix methods for the same pages. Conflicting signals are worse than one imperfect signal.
The value format
The attribute takes a language code, optionally followed by a region code.
|
Format |
Example |
Meaning |
|
Language only |
en |
English speakers anywhere |
|
Language and region |
en-sg |
English speakers in Singapore |
|
Special value |
x-default |
Fallback for users no other tag matches |
Language codes follow ISO 639-1. Region codes follow ISO 3166-1 Alpha 2. The order matters: language first, region second. There is no such thing as a region-only hreflang value.
The single most common syntax error is using a region code where a language belongs. hreflang=”sg” does not mean Singapore, it is read as a language code that does not exist. The correct value is en-sg.
Watch the codes that do not match the country name:
|
Country |
Correct code |
Commonly written as |
|
United Kingdom |
gb |
uk |
|
Japan |
jp with language ja |
jp-jp |
|
China |
cn with language zh |
ch |
|
Greece |
gr with language el |
gr-gr |
The five failures
In order of how often we find them.
1. Missing return links
This is the one that kills entire implementations. Hreflang must be reciprocal. If your Singapore page points to your Malaysia page, the Malaysia page must point back to Singapore.
Google’s rule is strict: if the return link is missing, the annotation is ignored. Not partially. The whole set.
This usually happens when a new market launches and someone adds the new page to the existing pages’ hreflang, but forgets to add the existing pages to the new one. Or when a page is added to the sitemap but not to the hreflang block.
2. The self-referencing tag is omitted
Every page must list itself. A Singapore page’s hreflang set must include hreflang=”en-sg” pointing at the Singapore page.
It feels redundant. It is required. Leave it out and the set is incomplete, with the same consequence as a missing return link.
3. Pointing at non-canonical or redirecting URLs
Hreflang must point at the final, indexable, canonical URL. Three variants break it:
- A URL that 301 redirects somewhere else
- A URL that canonicals to a different page
- A URL that is noindexed
The last combination is particularly confusing to diagnose, because the page exists, returns 200, and looks fine. Google just will not use it as an alternate.
A related trap: hreflang and canonical must agree. If a page canonicals to a different URL while also being listed as an hreflang alternate, you have told Google two contradictory things.
4. No x-default
x-default tells Google what to serve someone whose language and location match none of your tags. Without it, those users get whichever version Google picks.
For a Singapore business with /sg/, /my/ and /jp/ pages, a user in Germany matches nothing. With x-default pointing at your main or global page, they get a sensible result.
5. Relative URLs
Hreflang requires absolute URLs including the protocol. href=”/my/” is invalid. It must be href=”https://brand.com/my/”.
A worked example
Three markets, done correctly. Every page carries the identical block:
<link rel=“alternate” hreflang=“en-sg” href=“https://brand.com/sg/” />
<link rel=“alternate” hreflang=“en-my” href=“https://brand.com/my/” />
<link rel=“alternate” hreflang=“ja-jp” href=“https://brand.com/jp/” />
<link rel=“alternate” hreflang=“x-default” href=“https://brand.com/” />
That is the useful shortcut: the block is the same on every page in the cluster. If your Singapore page’s block differs from your Malaysia page’s block, something is wrong. This also makes it easy to template, which is how large sites avoid the return-link problem entirely.
Country targeting or language targeting?
Decide this before you write a single tag, because it determines your whole structure.
|
Language targeting |
Country targeting |
|
|
Example |
One Spanish page for Spain, Mexico and Colombia |
Separate pages per country |
|
Tag format |
es |
es-es, es-mx, es-co |
|
When it fits |
Same product, same price, same terms everywhere |
Different pricing, stock, currency or legal terms |
|
Cost |
One page to maintain |
One page per market |
Most Singapore companies expanding regionally need country targeting, because pricing, currency and delivery differ by market. But if your offer is genuinely identical across markets, language targeting is less work and performs just as well.
Do not use country targeting to create near-duplicate pages with nothing different on them. That creates the duplication problem hreflang was meant to solve.
How to verify it works
Four checks, in order.
Search Console’s International Targeting report. The fastest read on return-link errors and invalid codes. It reports at the property level, so a clean report here means the basics are right.
View source, not rendered DOM. Hreflang injected by JavaScript is unreliable. Use curl or view-source and confirm the tags are in the raw HTML.
Check one page from each market. Confirm the block is identical and that each version lists itself. This catches 80% of problems in five minutes.
Re-check after every release. This is the step everyone skips. Deployments break hreflang routinely, usually when a template changes or a market URL moves. Put it in your release QA alongside the other technical checks in our technical SEO guide and SEO audit checklist.
When hreflang is not your problem
Worth saying, because hreflang gets blamed for a lot it does not cause.
If your Malaysian pages are not ranking in Malaysia at all, hreflang is probably not the issue. Hreflang swaps between versions Google already ranks. If no version ranks, you have a relevance or authority problem in that market, and the fix is local content and local signals, not tags.
If your site structure puts markets on separate domains, each domain starts with zero authority and hreflang does nothing to share it. That is a structure decision, covered in our international SEO checklist.
If one language version outranks another for the same query within the same country, check for duplicate content and canonical conflicts before blaming hreflang.
Frequently asked questions
Is hreflang a ranking factor?
No. Hreflang does not improve rankings. It tells Google which language or country version to serve a given user, which prevents the wrong version appearing and stops your own versions competing. Correct hreflang protects performance rather than creating it.
Does hreflang need to be reciprocal?
Yes, strictly. Every version must point at every other version, and at itself. If a return link is missing, Google ignores the entire annotation set rather than just the broken pair. This is the single most common reason hreflang implementations fail.
What is x-default in hreflang?
x-default specifies the fallback page for users whose language and location match none of your other hreflang values. Without it, those users receive whichever version Google selects on its own.
Can I use hreflang=“uk” for the United Kingdom?
No. uk is not a valid region code in this context. The ISO 3166-1 code for the United Kingdom is gb, so the correct value is en-gb.
Should hreflang go in the head, the sitemap, or HTTP headers?
Any one of the three, used consistently. The HTML head is most common. The XML sitemap is better for large sites because you maintain one file rather than thousands of templates. HTTP headers are for non-HTML files. Do not mix methods for the same set of pages.
Does hreflang fix duplicate content?
Partly. It tells Google that near-identical pages are intentional alternates for different audiences rather than duplicates. It does not help if the pages are genuinely identical with no localisation, and it does not replace correct canonical tags.
Why is my hreflang showing errors in Search Console after a site update?
Deployments break hreflang routinely, usually when a template changes, a URL moves, or a new market page is added without updating the other versions. Add an hreflang check to your release QA rather than discovering it at the next audit.
Do I need hreflang if all my pages are in English?
Only if you have separate pages for different English-speaking markets, such as /sg/ and /my/, where you want Google to serve the right one by country. If you have one English page serving everyone, you do not need it.
Getting the structure right first
Hreflang only works on top of a sound structure. If your markets sit on the wrong kind of URL, correct tags will not rescue the setup.
If you are planning a market entry or fixing one that is not performing, our international SEO checklist covers the structure decision, and our international SEO service covers the implementation. For large sites where the same tags have to survive hundreds of template-generated pages, see enterprise SEO strategy.
