If your WordPress site serves content in multiple languages or targets different regions, implementing hreflang tags is essential for search engine optimization. Without them, Google and other search engines may show the wrong language version in their results or treat your translated pages as duplicate content, which dilutes your rankings across all language versions. Hreflang tags tell search engines exactly which language and regional variant each page represents, so users always land on the version most relevant to them.
What Hreflang Tags Are and How Search Engines Use Them
Hreflang is an HTML attribute that specifies the language (and optionally the geographic target) of a page. It appears as a <link> element in the <head> section of your page, or as an entry in your XML sitemap. Here is what a typical set of hreflang tags looks like for a page available in English and German:
<link rel="alternate" hreflang="en" href="https://example.com/en/about/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/ueber-uns/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/about/" />When Googlebot crawls a page and finds these tags, it understands that both URLs represent the same content in different languages. It then serves the appropriate version based on the searcher's language preferences and location. The x-default tag acts as a catch-all fallback for users whose language or region does not match any of the specified hreflang values.
Hreflang uses ISO 639-1 language codes (e.g., en, de, fr) and optionally ISO 3166-1 Alpha 2 country codes (e.g., en-US, de-AT, pt-BR). The language code alone targets all users of that language regardless of location, while adding a country code narrows the targeting to a specific region.
When You Need Regional vs. Language-Only Targeting
Choosing between language-only codes (like de) and region-specific codes (like de-DE, de-AT, de-CH) depends on your content strategy:
- Language-only (
de): Use this when your German content is suitable for all German-speaking users regardless of their country. This is the right choice for most blogs, informational sites, and SaaS products. - Region-specific (
de-DE,de-AT): Use this when you have separate content tailored to specific countries. For example, an e-commerce store with different product availability, pricing, or legal information for Germany vs. Austria vs. Switzerland needs region-specific tags.
A common mistake is using region-specific codes when language-only codes would suffice. If your German content is identical for all German speakers, using de is simpler and avoids the need to create separate pages for each region.
Setting Up Hreflang with WPML
WPML (WordPress Multilingual Plugin) is the most widely used premium multilingual plugin, and it handles hreflang tags automatically:
- Purchase and install WPML Multilingual CMS from wpml.org.
- Run the setup wizard. Choose your default language and add all the languages your site supports.
- Select your URL structure. WPML supports subdirectories (
/en/,/de/), subdomains (en.example.com), or separate domains. Subdirectories are the most common and easiest to manage. - Begin translating your content. For each post or page, click the "+" icon next to the target language in the WPML language box to create a translation.
- WPML automatically generates hreflang tags for every page that has translations. It also adds the
x-defaulttag pointing to your default language version.
To verify the output, view the source of any translated page and search for hreflang. You should see a <link> tag for each language, including the current page's language (a self-referencing hreflang, which is required).
WPML also integrates with Yoast SEO and Rank Math. When both plugins are active, the SEO plugin takes over hreflang generation and adds its own validation layer, which can catch common misconfigurations.
Setting Up Hreflang with Polylang
Polylang is a popular free alternative to WPML. It generates hreflang tags automatically for all linked translations:
- Install and activate Polylang from the WordPress plugin directory.
- Go to Languages > Languages and add each language your site supports. Set the locale, language code, and URL format (subdirectory is recommended).
- Assign a language to each existing post and page. Polylang adds a language column to your post list, making it easy to see which posts are translated.
- Link translations together. When editing a post, use the "Translations" box in the sidebar to connect it to its equivalent in other languages.
- Polylang automatically outputs hreflang tags in the
<head>for all linked translations.
One important difference from WPML: Polylang does not automatically add the x-default tag in all configurations. To ensure it is present, go to Languages > Settings > Hreflang and verify that x-default is set to your primary language. If you use Polylang Pro (the premium version), this is handled automatically.
Setting Up Hreflang with TranslatePress
TranslatePress takes a different approach by letting you translate content directly on the front end:
- Install and activate TranslatePress.
- Go to Settings > TranslatePress and add your languages.
- Click "Translate Site" in the admin toolbar to open the visual translation editor.
- Navigate to any page and click on text elements to translate them inline.
- TranslatePress automatically handles hreflang tag generation for all translated pages.
TranslatePress stores translations in the database rather than creating separate posts, which means your content management is simpler but the URL structure options are more limited.
Combining Yoast SEO or Rank Math with Multilingual Plugins
Both Yoast SEO and Rank Math detect popular multilingual plugins and take over hreflang tag generation when both are active. This integration adds extra validation:
- Canonical URL matching: The SEO plugin verifies that the hreflang href matches the canonical URL of each page, preventing a common misconfiguration.
- Noindex handling: Pages marked as noindex are automatically excluded from hreflang output, since search engines should not index them anyway.
- Sitemap integration: Hreflang annotations are included in the XML sitemap generated by the SEO plugin, providing search engines with a second source of hreflang data.
If you use Yoast SEO with WPML or Polylang, check SEO > General > Features and make sure the hreflang feature is not disabled. Rank Math handles this automatically without requiring any additional configuration.
Manual Hreflang Implementation in WordPress
For sites with a custom multilingual setup (e.g., using separate WordPress installations for each language, or a headless CMS approach), you may need to add hreflang tags manually:
function add_hreflang_tags() {
if (is_singular()) {
$post_id = get_the_ID();
// Define your language-to-URL mapping
// Store translations as post meta or in a custom table
$translations = array(
'en' => get_post_meta($post_id, '_url_en', true),
'de' => get_post_meta($post_id, '_url_de', true),
'fr' => get_post_meta($post_id, '_url_fr', true),
);
// Remove empty entries
$translations = array_filter($translations);
// Add the current page (self-referencing hreflang is required)
$current_lang = get_locale();
$lang_code = substr($current_lang, 0, 2); // 'en_US' becomes 'en'
$translations[$lang_code] = get_permalink();
// Output hreflang tags
foreach ($translations as $lang => $url) {
echo '<link rel="alternate" hreflang="' . esc_attr($lang) . '" href="' . esc_url($url) . '" />' . "
";
}
// x-default (usually points to English or your primary language)
if (!empty($translations['en'])) {
echo '<link rel="alternate" hreflang="x-default" href="' . esc_url($translations['en']) . '" />' . "
";
}
} elseif (is_front_page() || is_home()) {
// Handle the homepage separately
$home_translations = array(
'en' => 'https://example.com/en/',
'de' => 'https://example.com/de/',
'fr' => 'https://example.com/fr/',
);
foreach ($home_translations as $lang => $url) {
echo '<link rel="alternate" hreflang="' . esc_attr($lang) . '" href="' . esc_url($url) . '" />' . "
";
}
echo '<link rel="alternate" hreflang="x-default" href="' . esc_url($home_translations['en']) . '" />' . "
";
}
}
add_action('wp_head', 'add_hreflang_tags');In a production setup, you would replace the hardcoded URL arrays with dynamic lookups from your translation mapping system, whether that is post meta, a custom database table, or an API call to your translation management platform.
Adding Hreflang to XML Sitemaps
For sites with thousands of pages, declaring hreflang in your XML sitemap can be more efficient than adding tags to every page's HTML. The XML sitemap approach reduces page size and gives search engines a centralized source of hreflang data. Here is the XML format:
<url>
<loc>https://example.com/en/about/</loc>
<xhtml:link rel="alternate" hreflang="en"
href="https://example.com/en/about/" />
<xhtml:link rel="alternate" hreflang="de"
href="https://example.com/de/ueber-uns/" />
<xhtml:link rel="alternate" hreflang="x-default"
href="https://example.com/en/about/" />
</url>Both WPML and Polylang add hreflang annotations to their sitemaps automatically. If you use Yoast SEO alongside a multilingual plugin, Yoast includes hreflang in its sitemap as well. For manual implementations, you can use a plugin like "XML Sitemap Generator for Google" and customize the sitemap output to include hreflang entries.
You can use both HTML hreflang tags and XML sitemap annotations simultaneously. Google processes both and reconciles them. If there are conflicts between the two, Google uses its own heuristics to determine the correct mapping.
Critical Hreflang Rules You Must Follow
Hreflang is notoriously easy to implement incorrectly. Follow these rules to avoid common pitfalls:
- Bidirectional (reciprocal) linking is mandatory: If page A (English) includes an hreflang pointing to page B (German), then page B must also include an hreflang pointing back to page A. If the link is only one-directional, search engines ignore it entirely. This is the single most common hreflang error.
- Self-referencing hreflang is required: Every page must include an hreflang tag that points to itself. If your English page has hreflang tags for German and French versions, it must also have an hreflang tag for the English version pointing to its own URL.
- Use canonical URLs only: The URL in each hreflang tag must match the canonical URL of that page exactly. If a page has a
rel="canonical"tag pointing to a different URL, use the canonical URL in the hreflang tag, not the current page URL. - Every language variant needs the full set: If you have 4 language versions, every page variant must include all 4 hreflang tags plus x-default. Incomplete sets cause search engines to ignore the entire hreflang annotation for that page group.
- Pages must return a 200 status code: Do not include URLs in hreflang tags that redirect (301/302) or return errors (404/500). Search engines will flag these as hreflang errors and may eventually stop processing your hreflang annotations.
- Always include x-default: The x-default tag serves as a fallback for users whose language or region does not match any of your specified variants. Without it, those users may not see your content in search results at all.
Debugging and Validating Your Hreflang Implementation
After setting up hreflang tags, thorough validation is critical. Even small errors can render your entire hreflang setup ineffective:
- InspectWP analysis: Run each language version of your site through InspectWP. It detects all hreflang tags and lists each language variant, making it easy to verify that all tags are present and point to the correct URLs.
- Google Search Console: Check the International Targeting report (under Legacy tools and reports) for hreflang errors. Google reports issues like missing return links, unknown language codes, and hreflang conflicts with canonical tags.
- Manual source code inspection: View the source of each language version and verify that the hreflang tags are present, bidirectional, and self-referencing. Check that URLs are absolute (not relative) and use the correct protocol (https, not http).
- Ahrefs or Screaming Frog audit: For large sites, use a crawler tool to check all pages at once. These tools can identify missing hreflang tags, non-reciprocal links, and language code mismatches across your entire site.
Hreflang for WordPress Multisite Networks
If you run a WordPress Multisite where each subsite represents a different language, hreflang implementation requires cross-site awareness. WPML supports Multisite configurations, linking content across subsites. For manual implementations, you need to query the other subsites' databases to find the matching translated post and construct the hreflang URL dynamically. The switch_to_blog() function in WordPress lets you query another subsite's data within the same network.
Performance Considerations for Large Multilingual Sites
On sites with many languages (10+), the hreflang tags can add significant markup to every page. Each page needs one tag per language plus x-default, so a site with 15 languages adds 16 <link> elements to every page's head. For performance-sensitive sites, consider these strategies:
- Use XML sitemap hreflang instead of HTML: Moving hreflang declarations to the sitemap removes the markup from your pages entirely, reducing page size.
- Cache hreflang output: If you generate hreflang tags dynamically (e.g., from database queries), cache the result using WordPress transients or your object cache to avoid repeated database hits on every page load.
- Use HTTP headers for non-HTML content: For PDFs and other non-HTML resources, you can declare hreflang using HTTP
Linkheaders instead of HTML tags.