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?
- How does hreflang work?
- Rules for implementing hreflang
- Official ISO 639-1 Language Codes
- Official ISO 3166-1 Country Codes
- Got a question?
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.
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.
| Language | ISO Code |
| Abkhaz | ab |
| Afar | aa |
| Afrikaans | af |
| Akan | ak |
| Albanian | sq |
| Amharic | am |
| Arabic | ar |
| Aragonese | an |
| Armenian | hy |
| Assamese | as |
| Avaric | av |
| Avestan | ae |
| Aymara | ay |
| Azerbaijani | az |
| Bambara | bm |
| Bashkir | ba |
| Basque | eu |
| Belarusian | be |
| Bengali, Bangla | bn |
| Bihari | bh |
| Bislama | bi |
| Bosnian | bs |
| Breton | br |
| Bulgarian | bg |
| Burmese | my |
| Catalan, Valencian | ca |
| Chamorro | ch |
| Chechen | ce |
| Chichewa, Chewa, Nyanja | ny |
| Chinese | zh |
| Chuvash | cv |
| Cornish | kw |
| Corsican | co |
| Cree | cr |
| Croatian | hr |
| Czech | cs |
| Danish | da |
| Divehi, Dhivehi, Maldivian | dv |
| Dutch | nl |
| Dzongkha | dz |
| English | en |
| Esperanto | eo |
| Estonian | et |
| Ewe | ee |
| Faroese | fo |
| Fijian | fj |
| Finnish | fi |
| French | fr |
| Fula, Fulah, Pulaar, Pular | ff |
| Galician | gl |
| Georgian | ka |
| German | de |
| Greek (modern) | el |
| Guaraní | gn |
| Gujarati | gu |
| Haitian, Haitian Creole | ht |
| Hausa | ha |
| Hebrew (modern) | he |
| Herero | hz |
| Hindi | hi |
| Hiri Motu | ho |
| Hungarian | hu |
| Interlingua | ia |
| Indonesian | id |
| Interlingue | ie |
| Irish | ga |
| Igbo | ig |
| Inupiaq | ik |
| Ido | io |
| Icelandic | is |
| Italian | it |
| Inuktitut | iu |
| Japanese | ja |
| Javanese | jv |
| Kalaallisut, Greenlandic | kl |
| Kannada | kn |
| Kanuri | kr |
| Kashmiri | ks |
| Kazakh | kk |
| Khmer | km |
| Kikuyu, Gikuyu | ki |
| Kinyarwanda | rw |
| Kyrgyz | ky |
| Komi | kv |
| Kongo | kg |
| Korean | ko |
| Kurdish | ku |
| Kwanyama, Kuanyama | kj |
| Latin | la |
| Luxembourgish, Letzeburgesch | lb |
| Ganda | lg |
| Limburgish, Limburgan, Limburger | li |
| Lingala | ln |
| Lao | lo |
| Lithuanian | lt |
| Luba-Katanga | lu |
| Latvian | lv |
| Manx | gv |
| Macedonian | mk |
| Malagasy | mg |
| Malay | ms |
| Malayalam | ml |
| Maltese | mt |
| Māori | mi |
| Marathi (Marāṭhī) | mr |
| Marshallese | mh |
| Mongolian | mn |
| Nauru | na |
| Navajo, Navaho | nv |
| Northern Ndebele | nd |
| Nepali | ne |
| Ndonga | ng |
| Norwegian Bokmål | nb |
| Norwegian Nynorsk | nn |
| Norwegian | no |
| Nuosu | ii |
| Southern Ndebele | nr |
| Occitan | oc |
| Ojibwe, Ojibwa | oj |
| Old Church Slavonic, Church Slavonic, Old Bulgarian | cu |
| Oromo | om |
| Oriya | or |
| Ossetian, Ossetic | os |
| Panjabi, Punjabi | pa |
| Pāli | pi |
| Persian (Farsi) | fa |
| Polish | pl |
| Pashto, Pushto | ps |
| Portuguese | pt |
| Quechua | qu |
| Romansh | rm |
| Kirundi | rn |
| Romanian | ro |
| Russian | ru |
| Sanskrit (Saṁskṛta) | sa |
| Sardinian | sc |
| Sindhi | sd |
| Northern Sami | se |
| Samoan | sm |
| Sango | sg |
| Serbian | sr |
| Scottish Gaelic, Gaelic | gd |
| Shona | sn |
| Sinhala, Sinhalese | si |
| Slovak | sk |
| Slovene | sl |
| Somali | so |
| Southern Sotho | st |
| Spanish, Castilian | es |
| Sundanese | su |
| Swahili | sw |
| Swati | ss |
| Swedish | sv |
| Tamil | ta |
| Telugu | te |
| Tajik | tg |
| Thai | th |
| Tigrinya | ti |
| Tibetan Standard, Tibetan, Central | bo |
| Turkmen | tk |
| Tagalog | tl |
| Tswana | tn |
| Tonga (Tonga Islands) | to |
| Turkish | tr |
| Tsonga | ts |
| Tatar | tt |
| Twi | tw |
| Tahitian | ty |
| Uyghur, Uighur | ug |
| Ukrainian | uk |
| Urdu | ur |
| Uzbek | uz |
| Venda | ve |
| Vietnamese | vi |
| Volapük | vo |
| Walloon | wa |
| Welsh | cy |
| Wolof | wo |
| Western Frisian | fy |
| Xhosa | xh |
| Yiddish | yi |
| Yoruba | yo |
| Zhuang, Chuang | za |
| Zulu | zu |
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.
| Country | ISO Code |
| Afghanistan | AF |
| Åland Islands | AX |
| Albania | AL |
| Algeria | DZ |
| American Samoa | AS |
| Andorra | AD |
| Angola | AO |
| Anguilla | AI |
| Antarctica | AQ |
| Antigua and Barbuda | AG |
| Argentina | AR |
| Armenia | AM |
| Aruba | AW |
| Australia | AU |
| Austria | AT |
| Azerbaijan | AZ |
| Bahamas | BS |
| Bahrain | BH |
| Bangladesh | BD |
| Barbados | BB |
| Belarus | BY |
| Belgium | BE |
| Belize | BZ |
| Benin | BJ |
| Bermuda | BM |
| Bhutan | BT |
| Bolivia, Plurinational State of | BO |
| Bonaire, Sint Eustatius and Saba | BQ |
| Bosnia and Herzegovina | BA |
| Botswana | BW |
| Bouvet Island | BV |
| Brazil | BR |
| British Indian Ocean Territory | IO |
| Brunei Darussalam | BN |
| Bulgaria | BG |
| Burkina Faso | BF |
| Burundi | BI |
| Cambodia | KH |
| Cameroon | CM |
| Canada | CA |
| Cabo Verde | CV |
| Cayman Islands | KY |
| Central African Republic | CF |
| Chad | TD |
| Chile | CL |
| China | CN |
| Christmas Island | CX |
| Cocos (Keeling) Islands | CC |
| Colombia | CO |
| Comoros | KM |
| Congo | CG |
| Congo, the Democratic Republic of the | CD |
| Cook Islands | CK |
| Costa Rica | CR |
| Côte d’Ivoire | CI |
| Croatia | HR |
| Cuba | CU |
| Curaçao | CW |
| Cyprus | CY |
| Czech Republic | CZ |
| Denmark | DK |
| Djibouti | DJ |
| Dominica | DM |
| Dominican Republic | DO |
| Ecuador | EC |
| Egypt | EG |
| El Salvador | SV |
| Equatorial Guinea | GQ |
| Eritrea | ER |
| Estonia | EE |
| Ethiopia | ET |
| Falkland Islands (Malvinas) | FK |
| Faroe Islands | FO |
| Fiji | FJ |
| Finland | FI |
| France | FR |
| French Guiana | GF |
| French Polynesia | PF |
| French Southern Territories | TF |
| Gabon | GA |
| Gambia | GM |
| Georgia | GE |
| Germany | DE |
| Ghana | GH |
| Gibraltar | GI |
| Greece | GR |
| Greenland | GL |
| Grenada | GD |
| Guadeloupe | GP |
| Guam | GU |
| Guatemala | GT |
| Guernsey | GG |
| Guinea | GN |
| Guinea-Bissau | GW |
| Guyana | GY |
| Haiti | HT |
| Heard Island and McDonald Islands | HM |
| Holy See (Vatican City State) | VA |
| Honduras | HN |
| Hong Kong | HK |
| Hungary | HU |
| Iceland | IS |
| India | IN |
| Indonesia | ID |
| Iran, Islamic Republic of | IR |
| Iraq | IQ |
| Ireland | IE |
| Isle of Man | IM |
| Israel | IL |
| Italy | IT |
| Jamaica | JM |
| Japan | JP |
| Jersey | JE |
| Jordan | JO |
| Kazakhstan | KZ |
| Kenya | KE |
| Kiribati | KI |
| Korea, Democratic People’s Republic of | KP |
| Korea, Republic of | KR |
| Kuwait | KW |
| Kyrgyzstan | KG |
| Lao People’s Democratic Republic | LA |
| Latvia | LV |
| Lebanon | LB |
| Lesotho | LS |
| Liberia | LR |
| Libya | LY |
| Liechtenstein | LI |
| Lithuania | LT |
| Luxembourg | LU |
| Macao | MO |
| Macedonia, the former Yugoslav Republic of | MK |
| Madagascar | MG |
| Malawi | MW |
| Malaysia | MY |
| Maldives | MV |
| Mali | ML |
| Malta | MT |
| Marshall Islands | MH |
| Martinique | MQ |
| Mauritania | MR |
| Mauritius | MU |
| Mayotte | YT |
| Mexico | MX |
| Micronesia, Federated States of | FM |
| Moldova, Republic of | MD |
| Monaco | MC |
| Mongolia | MN |
| Montenegro | ME |
| Montserrat | MS |
| Morocco | MA |
| Mozambique | MZ |
| Myanmar | MM |
| Namibia | NA |
| Nauru | NR |
| Nepal | NP |
| Netherlands | NL |
| New Caledonia | NC |
| New Zealand | NZ |
| Nicaragua | NI |
| Niger | NE |
| Nigeria | NG |
| Niue | NU |
| Norfolk Island | NF |
| Northern Mariana Islands | MP |
| Norway | NO |
| Oman | OM |
| Pakistan | PK |
| Palau | PW |
| Palestine, State of | PS |
| Panama | PA |
| Papua New Guinea | PG |
| Paraguay | PY |
| Peru | PE |
| Philippines | PH |
| Pitcairn | PN |
| Poland | PL |
| Portugal | PT |
| Puerto Rico | PR |
| Qatar | QA |
| Réunion | RE |
| Romania | RO |
| Russian Federation | RU |
| Rwanda | RW |
| Saint Barthélemy | BL |
| Saint Helena, Ascension and Tristan da Cunha | SH |
| Saint Kitts and Nevis | KN |
| Saint Lucia | LC |
| Saint Martin (French part) | MF |
| Saint Pierre and Miquelon | PM |
| Saint Vincent and the Grenadines | VC |
| Samoa | WS |
| San Marino | SM |
| Sao Tome and Principe | ST |
| Saudi Arabia | SA |
| Senegal | SN |
| Serbia | RS |
| Seychelles | SC |
| Sierra Leone | SL |
| Singapore | SG |
| Sint Maarten (Dutch part) | SX |
| Slovakia | SK |
| Slovenia | SI |
| Solomon Islands | SB |
| Somalia | SO |
| South Africa | ZA |
| South Georgia and the South Sandwich Islands | GS |
| South Sudan | SS |
| Spain | ES |
| Sri Lanka | LK |
| Sudan | SD |
| Suriname | SR |
| Svalbard and Jan Mayen | SJ |
| Swaziland | SZ |
| Sweden | SE |
| Switzerland | CH |
| Syrian Arab Republic | SY |
| Taiwan, Province of China | TW |
| Tajikistan | TJ |
| Tanzania, United Republic of | TZ |
| Thailand | TH |
| Timor-Leste | TL |
| Togo | TG |
| Tokelau | TK |
| Tonga | TO |
| Trinidad and Tobago | TT |
| Tunisia | TN |
| Turkey | TR |
| Turkmenistan | TM |
| Turks and Caicos Islands | TC |
| Tuvalu | TV |
| Uganda | UG |
| Ukraine | UA |
| United Arab Emirates | AE |
| United Kingdom | GB |
| United States | US |
| United States Minor Outlying Islands | UM |
| Uruguay | UY |
| Uzbekistan | UZ |
| Vanuatu | VU |
| Venezuela, Bolivarian Republic of | VE |
| Viet Nam | VN |
| Virgin Islands, British | VG |
| Virgin Islands, U.S. | VI |
| Wallis and Futuna | WF |
| Western Sahara | EH |
| Yemen | YE |
| Zambia | ZM |
| Zimbabwe | ZW |
