A Guide to hreflang

A

This guide is for anyone who runs an international website with versions of the site available for specific markets or in different languages, or both! For example, you might have a version of the site for the New Zealand market and additional versions for Australia, the UK and Canada. For Canada you might also have versions in English and French.

In this guide we will explain why and how to use Hreflang. Hreflang is a meta data standard developed by Google and intended for use by international websites as described above. When used across the various versions of your website it helps Google (and other search engines) understand the relationship between similar pages intended for different markets. In short, it helps make sure that the correct version of your site ranks in the intended market.

Quick Links:

Why does hreflang Matter?

Hreflang matters because without it there is a good chance that the wrong version of your site will rank in a given market, e.g. we often see the US or global version of a site ranking in local markets like New Zealand or Australia even though there is a local version of the given page available. If you run an international site you’ve almost certainly seen this happen.

This situation arises when a site has multiple versions of the same (or similar) content, each intended for a specific market, but when Google indexes these pages and weigh up all the ranking factors, one version comes out on top…and it isn’t always the one you intended.

Keep in mind that Google considers hundreds of ranking factors, but some have an outsized impact on rankings. For example, if the US version of your page has many more links than the local version (and possibly some from local sites) then the ranking algorithm may determine that this is the best version of the page to show all things considered. Google is smart but sometimes they don’t get it right,

There are many reasons why this can happen. Hreflang is our chance to make it clear to Google which versions of a page are intended for which markets so that when they rank your site locally it is the intended local version which shows up.

Hreflang is currently supported by Google and Yandex, though Bing does not support the tag, instead relying on the traditional HTML meta language tag, so you will want to make sure those are accurate too.

How does hreflang work?

Hreflang is a standard for providing Google with links to alternate versions of a page along with a signal about what languages and/or countries that alternate version is intended for. Hreflang tags can be implemented in the <head> of the page, in an XML sitemap, or in the HTTP headers. The HTTP headers approach is rarely used, so here we’ll cover the two most common approaches, in the <head> of the page or in the XML sitemap.

Implementing hreflang in the <head>

For example, if the root of your domain (your home page) is in English (en), but you have directories for Spanish (es) and French (fr) versions of the site then you would add hreflang tags in the <head> of your home page like this…

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

Note:

  • The language codes used in Hreflang must be official ISO 639-1 codes.
  • These same tags would also need to appear on the alternate versions of the page and they must be self referencing, i.e. you must include a tag which references the current page along with the hreflang tag indicating which language the current page is intended for. The “x-fault” tag signals to Google that this version of the page is the one that should show up for any searchers not covered by other pages.
how hreflang works
Hreflang tags point to the alternative versions of the page, but must also be self referencing.

In the code example above we outlined a simple scenario where the root of the domain is in English while the directories have alternative language versions for users searching in those languages.

Things can get more complex when you are also targeting specific countries with a given language, for example in Canada you might have two versions of the page, one for English (en) and one for French (fr), but you might also have a separate French page for users in France. In this case your hreflang tags might look like this…

<link rel="alternate" href="https://example.com/" hreflang="x-default" />
<link rel="alternate" href="https://example.com/" hreflang="en" />
<link rel="alternate" href="https://example.com/es/" hreflang="es" />
<link rel="alternate" href="https://example.com/fr/" hreflang="fr" />
<link rel="alternate" href="https://example.com/fr-fr/" hreflang="fr-fr" />
<link rel="alternate" href="https://example.com/fr-ca/" hreflang="fr-ca" />
<link rel="alternate" href="https://example.com/en-ca/" hreflang="en-ca" />

In such cases we add the official country code after the language code to indicate that the page in question is intended for people using that specific language in that particular country. When using country codes they must be the official ISO 3166-1 Country Codes.

In the example above we have the following:

  • The main English (en) page, which is also the default anyone not covered by other versions.
  • A Spanish (es) version for any Spanish users regardless of location.
  • A French version for users in France (fr-fr)
  • A French version for users in Canada (fr-ca)
  • An Egnlish version for users in Canada (en-ca)
  • And we linked to a French (fr) version for any French speakers not in France or Canada . This hreflang tag could also have been linked to one of the other URLs.

You can see how this can quickly get a little complicated if you have many versions of the site. Thankfully most most Content Management Systems (CMS) which have built in multi-language capability will handle the hreflang tags automatically for you as you add new versions of pages.

Implementing hreflang in an xml sitemap

Above we explained how Hreflang works, this is the same if you are implementing in your XML sitemaps, only format of the XML document is of course different. For example, if we take our first simple example from above and implement that in an XML site map it would look like this…

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

Notice that each URL still has a self referencing Hreflang tag, and all pages have reciprocal references as well. This is required whether you implement as meta data in the <head> of the HTML document or in an XML sitemap.

Rules for implementing hreflang

So now you know how hreflang works, here are some guidelines and rules for implementing hreflang on your site:

  • All the links used in hreflang tags must be fully qualified URLs, which means they must include everything from the protocol forward, i.e. https://…
  • All pages should also include a self referencing hreflang tag.
  • All hreflang references must be reciprocal, ie. if one page refers to another version of the page, then that other page must also refer back with a corresponding hreflang tag.
  • Hreflang tags must point to the canonical version of a page, i.e. do not reference a page in an hreflang tag that redirects somewhere else or has a canonical tag pointing to a different URL.
  • For hreflang to be valid you must use the official ISO 639-1 Language Codes and ISO 3166-1 Country Codes. We’ve included these below for easy reference.
  • It is ok to reference the same URL in multiple Hreflang tags if that page is intended to serve multiple locations, or if that page is also the global default (x-default). As in the above examples the English (en) language page has an hreflang tag indicating that it is for English speaking audiences and it has another indicating that it is the global default (x-default) for all visitors not covered by other pages.
  • Hreflang tags can refer to pages on other domains. For example, if you have country code top level domains (ccTLD) for each market then you can refer to the equivalent pages on each domain. That said, when you are using ccTLDs that is already a very strong signal about which market you are targeting with that domain so Hreflang is arguably less important. Some businesses like Expedia use a combination of ccTLDs and sub-directories on the main .com domain. Expedia’s Hreflang implementation refers to both, and is actually a pretty good example to checkout.
  • If you have a large site with hundreds or thousands of pages it can be difficult to audit your Hreflang implementation to ensure it is implemented correctly. Tools like Screaming Frog and Sitebulb are a worthwhile investment as they can more or less automate this analysis.

You can learn more about hreflang implementation from Google’s own documentation here.

Official ISO 639-1 Language Codes

This table includes all the official 2-letter language codes that are valid for Hreflang. If you do not use these codes then your Hreflang will not be valid.

LanguageISO Code
Abkhazab
Afaraa
Afrikaansaf
Akanak
Albaniansq
Amharicam
Arabicar
Aragonesean
Armenianhy
Assameseas
Avaricav
Avestanae
Aymaraay
Azerbaijaniaz
Bambarabm
Bashkirba
Basqueeu
Belarusianbe
Bengali, Banglabn
Biharibh
Bislamabi
Bosnianbs
Bretonbr
Bulgarianbg
Burmesemy
Catalan, Valencianca
Chamorroch
Chechence
Chichewa, Chewa, Nyanjany
Chinesezh
Chuvashcv
Cornishkw
Corsicanco
Creecr
Croatianhr
Czechcs
Danishda
Divehi, Dhivehi, Maldiviandv
Dutchnl
Dzongkhadz
Englishen
Esperantoeo
Estonianet
Eweee
Faroesefo
Fijianfj
Finnishfi
Frenchfr
Fula, Fulah, Pulaar, Pularff
Galiciangl
Georgianka
Germande
Greek (modern)el
Guaranígn
Gujaratigu
Haitian, Haitian Creoleht
Hausaha
Hebrew (modern)he
Hererohz
Hindihi
Hiri Motuho
Hungarianhu
Interlinguaia
Indonesianid
Interlingueie
Irishga
Igboig
Inupiaqik
Idoio
Icelandicis
Italianit
Inuktitutiu
Japaneseja
Javanesejv
Kalaallisut, Greenlandickl
Kannadakn
Kanurikr
Kashmiriks
Kazakhkk
Khmerkm
Kikuyu, Gikuyuki
Kinyarwandarw
Kyrgyzky
Komikv
Kongokg
Koreanko
Kurdishku
Kwanyama, Kuanyamakj
Latinla
Luxembourgish, Letzeburgeschlb
Gandalg
Limburgish, Limburgan, Limburgerli
Lingalaln
Laolo
Lithuanianlt
Luba-Katangalu
Latvianlv
Manxgv
Macedonianmk
Malagasymg
Malayms
Malayalamml
Maltesemt
Māorimi
Marathi (Marāṭhī)mr
Marshallesemh
Mongolianmn
Nauruna
Navajo, Navahonv
Northern Ndebelend
Nepaline
Ndongang
Norwegian Bokmålnb
Norwegian Nynorsknn
Norwegianno
Nuosuii
Southern Ndebelenr
Occitanoc
Ojibwe, Ojibwaoj
Old Church Slavonic, Church Slavonic, Old Bulgariancu
Oromoom
Oriyaor
Ossetian, Osseticos
Panjabi, Punjabipa
Pālipi
Persian (Farsi)fa
Polishpl
Pashto, Pushtops
Portuguesept
Quechuaqu
Romanshrm
Kirundirn
Romanianro
Russianru
Sanskrit (Saṁskṛta)sa
Sardiniansc
Sindhisd
Northern Samise
Samoansm
Sangosg
Serbiansr
Scottish Gaelic, Gaelicgd
Shonasn
Sinhala, Sinhalesesi
Slovaksk
Slovenesl
Somaliso
Southern Sothost
Spanish, Castilianes
Sundanesesu
Swahilisw
Swatiss
Swedishsv
Tamilta
Telugute
Tajiktg
Thaith
Tigrinyati
Tibetan Standard, Tibetan, Centralbo
Turkmentk
Tagalogtl
Tswanatn
Tonga (Tonga Islands)to
Turkishtr
Tsongats
Tatartt
Twitw
Tahitianty
Uyghur, Uighurug
Ukrainianuk
Urduur
Uzbekuz
Vendave
Vietnamesevi
Volapükvo
Walloonwa
Welshcy
Wolofwo
Western Frisianfy
Xhosaxh
Yiddishyi
Yorubayo
Zhuang, Chuangza
Zuluzu

Official ISO 3166-1 Country Codes

This table includes all the official 2-letter country codes that are valid for Hreflang. If you do not use these codes then your Hreflang will not be valid.

CountryISO Code
AfghanistanAF
Åland IslandsAX
AlbaniaAL
AlgeriaDZ
American SamoaAS
AndorraAD
AngolaAO
AnguillaAI
AntarcticaAQ
Antigua and BarbudaAG
ArgentinaAR
ArmeniaAM
ArubaAW
AustraliaAU
AustriaAT
AzerbaijanAZ
BahamasBS
BahrainBH
BangladeshBD
BarbadosBB
BelarusBY
BelgiumBE
BelizeBZ
BeninBJ
BermudaBM
BhutanBT
Bolivia, Plurinational State ofBO
Bonaire, Sint Eustatius and SabaBQ
Bosnia and HerzegovinaBA
BotswanaBW
Bouvet IslandBV
BrazilBR
British Indian Ocean TerritoryIO
Brunei DarussalamBN
BulgariaBG
Burkina FasoBF
BurundiBI
CambodiaKH
CameroonCM
CanadaCA
Cabo VerdeCV
Cayman IslandsKY
Central African RepublicCF
ChadTD
ChileCL
ChinaCN
Christmas IslandCX
Cocos (Keeling) IslandsCC
ColombiaCO
ComorosKM
CongoCG
Congo, the Democratic Republic of theCD
Cook IslandsCK
Costa RicaCR
Côte d’IvoireCI
CroatiaHR
CubaCU
CuraçaoCW
CyprusCY
Czech RepublicCZ
DenmarkDK
DjiboutiDJ
DominicaDM
Dominican RepublicDO
EcuadorEC
EgyptEG
El SalvadorSV
Equatorial GuineaGQ
EritreaER
EstoniaEE
EthiopiaET
Falkland Islands (Malvinas)FK
Faroe IslandsFO
FijiFJ
FinlandFI
FranceFR
French GuianaGF
French PolynesiaPF
French Southern TerritoriesTF
GabonGA
GambiaGM
GeorgiaGE
GermanyDE
GhanaGH
GibraltarGI
GreeceGR
GreenlandGL
GrenadaGD
GuadeloupeGP
GuamGU
GuatemalaGT
GuernseyGG
GuineaGN
Guinea-BissauGW
GuyanaGY
HaitiHT
Heard Island and McDonald IslandsHM
Holy See (Vatican City State)VA
HondurasHN
Hong KongHK
HungaryHU
IcelandIS
IndiaIN
IndonesiaID
Iran, Islamic Republic ofIR
IraqIQ
IrelandIE
Isle of ManIM
IsraelIL
ItalyIT
JamaicaJM
JapanJP
JerseyJE
JordanJO
KazakhstanKZ
KenyaKE
KiribatiKI
Korea, Democratic People’s Republic ofKP
Korea, Republic ofKR
KuwaitKW
KyrgyzstanKG
Lao People’s Democratic RepublicLA
LatviaLV
LebanonLB
LesothoLS
LiberiaLR
LibyaLY
LiechtensteinLI
LithuaniaLT
LuxembourgLU
MacaoMO
Macedonia, the former Yugoslav Republic ofMK
MadagascarMG
MalawiMW
MalaysiaMY
MaldivesMV
MaliML
MaltaMT
Marshall IslandsMH
MartiniqueMQ
MauritaniaMR
MauritiusMU
MayotteYT
MexicoMX
Micronesia, Federated States ofFM
Moldova, Republic ofMD
MonacoMC
MongoliaMN
MontenegroME
MontserratMS
MoroccoMA
MozambiqueMZ
MyanmarMM
NamibiaNA
NauruNR
NepalNP
NetherlandsNL
New CaledoniaNC
New ZealandNZ
NicaraguaNI
NigerNE
NigeriaNG
NiueNU
Norfolk IslandNF
Northern Mariana IslandsMP
NorwayNO
OmanOM
PakistanPK
PalauPW
Palestine, State ofPS
PanamaPA
Papua New GuineaPG
ParaguayPY
PeruPE
PhilippinesPH
PitcairnPN
PolandPL
PortugalPT
Puerto RicoPR
QatarQA
RéunionRE
RomaniaRO
Russian FederationRU
RwandaRW
Saint BarthélemyBL
Saint Helena, Ascension and Tristan da CunhaSH
Saint Kitts and NevisKN
Saint LuciaLC
Saint Martin (French part)MF
Saint Pierre and MiquelonPM
Saint Vincent and the GrenadinesVC
SamoaWS
San MarinoSM
Sao Tome and PrincipeST
Saudi ArabiaSA
SenegalSN
SerbiaRS
SeychellesSC
Sierra LeoneSL
SingaporeSG
Sint Maarten (Dutch part)SX
SlovakiaSK
SloveniaSI
Solomon IslandsSB
SomaliaSO
South AfricaZA
South Georgia and the South Sandwich IslandsGS
South SudanSS
SpainES
Sri LankaLK
SudanSD
SurinameSR
Svalbard and Jan MayenSJ
SwazilandSZ
SwedenSE
SwitzerlandCH
Syrian Arab RepublicSY
Taiwan, Province of ChinaTW
TajikistanTJ
Tanzania, United Republic ofTZ
ThailandTH
Timor-LesteTL
TogoTG
TokelauTK
TongaTO
Trinidad and TobagoTT
TunisiaTN
TurkeyTR
TurkmenistanTM
Turks and Caicos IslandsTC
TuvaluTV
UgandaUG
UkraineUA
United Arab EmiratesAE
United KingdomGB
United StatesUS
United States Minor Outlying IslandsUM
UruguayUY
UzbekistanUZ
VanuatuVU
Venezuela, Bolivarian Republic ofVE
Viet NamVN
Virgin Islands, BritishVG
Virgin Islands, U.S.VI
Wallis and FutunaWF
Western SaharaEH
YemenYE
ZambiaZM
ZimbabweZW

About the author

Charles

Charles has been working on the web for 20 years, building and promoting websites in New Zealand, Australia, the US and China.

Add Comment

By Charles

Get in touch

Paul - (027) 513 6134
Charles - (021) 807 829


Paul - (027) 513 6134
Charles - (021) 807 829