SEO & AI search · Guide
How to Add Hreflang Tags in WordPress
Short answer
Add hreflang tags in WordPress with a multilingual plugin such as Polylang or WPML, which writes the tags for you once translations are linked. You can also add them by hand in your theme, through an XML sitemap, or with a small code snippet. Whichever method you pick, every language version must list itself and all the others, with full URLs, and the pages must point back at each other.
Key takeaways
- A multilingual plugin such as Polylang or WPML writes hreflang tags for you once translations are linked.
- Google accepts three methods: HTML tags, HTTP headers, and sitemaps, and all three are equal.
- Every language version must list itself and all the others, with full URLs.
- Two pages must point back at each other, or Google ignores the tags.
- Use ISO 639-1 language codes with an optional ISO 3166-1 region code, such as en-US.
What are hreflang tags?
Hreflang tags tell search engines which language and region each version of a page is for.
A hreflang tag is a small piece of HTML in the <head> of a page. It looks like this: <link rel="alternate" hreflang="en-US" href="https://example.com/" />. The hreflang value names the language, and the href value gives the full URL of that version.
Google introduced the hreflang attribute in 2011 to help search engines show the right language version to each searcher, as Polylang explains in its hreflang guide. A French article can then appear on google.fr, while the English version appears on google.com.
Hreflang does not translate your content. It only maps versions that already exist, so you need real translated pages before the tags do any good.
When do you need hreflang tags?
You need hreflang tags when the same content exists in more than one language or for more than one region.
Google lists three cases where it recommends marking alternate pages (Google Search Central).
One case is translating only the template, such as navigation and footer, while the main content stays in one language. Another is small regional variations in one language, such as English for the US, the UK, and Ireland. The third is content fully translated into several languages.
You do not need hreflang on a single-language site. You also do not need it when two pages cover different topics in different languages, since they are not versions of the same page.
Localized versions are only treated as duplicates when the main content stays untranslated, according to the same Google page. Full translations are separate pages in their own right, and hreflang simply connects them.
What are the three ways to add hreflang tags?
Google accepts three methods for marking alternate pages: HTML tags, HTTP headers, and sitemaps.
All three methods are equal in Google's eyes, and you can pick the one that fits your site. Google says there is no benefit in using all three at once, and that running three copies is much harder to manage (Google Search Central).
| Method | How it works | Best for |
|---|---|---|
| HTML tags | <link> tags in the page <head> | Most WordPress sites |
| HTTP headers | Link: headers in the server response | PDFs and other non-HTML files |
| Sitemap | <xhtml:link> entries in the XML sitemap | Large sites with many translations |
On WordPress, the HTML method is the usual pick, and a multilingual plugin writes the tags for you. The sitemap method suits sites that already manage translations through an SEO plugin, as covered in the section below.
How do you add hreflang tags with Polylang?
Install Polylang, add your languages, link the translations, and Polylang writes the tags for you.
- Go to Plugins → Add New, search for Polylang, then install and activate it.
- Go to Languages → Languages and add each language your site uses.
- Open a post or page, pick a language in the sidebar, and link it to its translation.
- View the page source and look for
<link rel="alternate" hreflang="...">tags in the<head>.
Polylang adds the tags automatically once translations are linked, and you do not need to do anything else, as its hreflang guide states. It reads the WordPress locale for each language, so en_US becomes en-US in the tag, following the standard format.
If you add a new language later, link its translations before you publish. A translation that is not linked to the original gets no hreflang tag, and Google sees it as a standalone page.
How do you add hreflang tags with WPML?
WPML also writes hreflang tags on its own as you translate content, with no extra setup.
WPML inserts <link rel="alternate" hreflang="..."> tags in the <head> of every page, pointing each page at its translations, according to its URLs and SEO documentation. The tags update on their own as you add or change translations.
WPML offers three URL formats for languages: directories such as yoursite.com/fr/, separate domains such as yoursite.fr, and a language parameter such as ?lang=fr. Pick the format once at setup, since switching later breaks inbound links. WPML advises subfolders or subdomains, and warns that the parameter format is treated poorly by Google (WPML).
If you use the WPML SEO add-on with a Yoast SEO or Rank Math sitemap, WPML moves the hreflang tags into the sitemap instead of the page head. Our Yoast setup guide covers the sitemap settings you need for that to work.
How do you add hreflang tags by hand in code?
Add one <link> tag per language version in the <head>, including the page itself.
Every version of the page carries the same set of tags, one for each version including itself. Google states that each language version must list itself as well as all other language versions (Google Search Central).
Here is the set for a page in English, British English, and German:
<link rel="alternate" hreflang="en" href="https://example.com/page/" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/page/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/page/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page/" />
Use full URLs with https://, never relative paths such as /page/. Google requires alternate URLs to be fully qualified, including the transport method, and gives https://example.com/foo as the correct form (Google Search Central).
In WordPress, add these tags with a small code snippet in a child theme or a code-snippets plugin, hooked to wp_head. Do not edit the parent theme directly, since an update will wipe the change.
How do you add hreflang tags through your XML sitemap?
List every language version inside each <url> entry of your sitemap, using <xhtml:link> tags.
Each <url> entry gets one child <xhtml:link> per version, including itself, and the set is the same across all versions of the page. Google explains that if a page has 3 versions, each sitemap entry carries 3 identical child entries (Google Search Central).
<url>
<loc>https://www.example.com/english/page.html</loc>
<xhtml:link rel="alternate" hreflang="de" href="https://www.example.de/deutsch/page.html"/>
<xhtml:link rel="alternate" hreflang="en" href="https://www.example.com/english/page.html"/>
</url>
The sitemap must declare the xhtml namespace, xmlns:xhtml="http://www.w3.org/1999/xhtml", or the tags will not parse. WordPress has built a basic sitemap at /wp-sitemap.xml since version 5.5, with up to 2,000 URLs per sitemap file, according to the Make WordPress Core announcement.
An SEO plugin sitemap is the easier route on most sites. Yoast and Rank Math build the sitemap for you, and WPML or Polylang adds the hreflang entries to it. Our sitemap fix guide helps when the sitemap itself returns an error.
How do you check that your hreflang tags work?
Check the tags in three places: the page source, Search Console, and a hreflang testing tool.
First, open a translated page, view the page source, and search for hreflang. You should see one tag per version, including the page itself, with full URLs. If a version is missing, its translation is probably not linked in your multilingual plugin.
Second, open Google Search Console and look for hreflang errors on your property. Google lists errors such as missing return links and wrong language codes there, so fix the ones it flags first.
Third, run the URL through a hreflang checker, which loads each version and confirms the tags point back at each other. Google ignores tags when two pages do not both point to each other, so a one-way link is the same as no link at all (Google Search Central).
What do the language and region codes mean?
A hreflang value is a language code, with an optional region code after a dash, such as en-US.
The language code uses the ISO 639-1 format, and the region code uses the ISO 3166-1 Alpha 2 format. Google only supports codes from those two lists, and notes that codes such as es-419 are not supported (Google Search Central).
| Code | Meaning |
|---|---|
en | English, any region |
en-US | English for the United States |
en-GB | English for the United Kingdom |
de | German, any region |
de-CH | German for Switzerland |
fr | French, any region |
x-default | Fallback page for unmatched languages |
The x-default value marks the fallback page for visitors whose language matches none of your versions, often a language selector or the home page. Polylang only adds x-default on its own to an auto-redirected home page, and you can add it elsewhere with the pll_rel_hreflang_attributes filter (Polylang).
Google does not use hreflang or the HTML lang attribute to detect the language of a page; it uses its own algorithms for that. Hreflang only tells Google which version to show, not what language the page is written in.
What mistakes should you avoid?
The most common mistake is adding hreflang tags that point only one way.
- Do not list a version on one page and forget it on the other; both pages must point at each other.
- Do not use relative URLs in hreflang tags; always use full URLs with
https://. - Do not mix methods without a plan; pick HTML, headers, or sitemap and keep one copy.
- Do not add hreflang to pages that are not true translations of each other.
- Do not use a made-up region code; stick to ISO 639-1 language codes and ISO 3166-1 region codes.
If you use a multilingual plugin, let it write the tags and check the output, rather than adding a second set by hand. Two sets of tags from two sources will disagree, and Google will ignore the broken ones.
For related setup steps, our schema markup guide covers another kind of markup that pairs with hreflang on multilingual sites.
Frequently asked questions
Can Yoast SEO or Rank Math add hreflang tags for me?
Yes, but only through a multilingual plugin such as Polylang or WPML, or by adding the tags by hand. Yoast SEO and Rank Math do not create translations, so they cannot write hreflang tags on their own. They do build the XML sitemap that WPML or Polylang can add hreflang entries to.
Why is Google ignoring my hreflang tags?
Google ignores the tags when two pages do not point back at each other. This rule stops a site from naming itself as the alternate version of someone else's page. Check the page source on both versions and confirm each one lists the other, with the same full URLs.
Should I use HTML tags or a sitemap for hreflang?
Use one method for the whole site. HTML tags suit most WordPress sites, since a multilingual plugin writes them for you. The sitemap method suits large sites with many translations. Google says all three methods are equal, and using more than one brings no benefit.
What is the x-default hreflang value for?
The x-default tag marks the fallback page for visitors whose language matches none of your versions. It often points at a language selector page or the home page. Polylang only adds it on its own to an auto-redirected home page, so add it by hand or with a filter on other pages.
Do hreflang tags improve my rankings?
Yes. hreflang only tells Google which version to show to which searcher. It does not create translations, rank pages, or detect the language of a page. You still need full, real translations, good content, and links before the tags change what anyone sees.
Do I need a separate hreflang tag for every language on every page?
No. You need one set of tags per page, with one tag for each language version including the page itself. Every version carries the same set. If you add a fourth language later, update the set on all four versions, not just on the new page.
Sources
- Localized Versions of your Pages Google Search Central
- Hreflang tag attributes and Polylang Polylang
- Customize URLs, Slugs, and SEO in WPML WPML
- Merge Announcement: Extensible Core Sitemaps Make WordPress Core
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
