How to Set Up Hreflang Tags for Multi-Language SEO in Magento 2
Hreflang tags tell search engines which language and regional version of a page to display in search results. For multi-language Magento stores, proper hreflang implementation prevents duplicate content issues and ensures visitors see the correct language version of your store.
How Hreflang Tags Work
Hreflang tags are HTML link elements in the <head> section of a page:
<link rel="alternate" hreflang="en-us" href="https://example.com/product.html" />
<link rel="alternate" hreflang="de-de" href="https://example.de/product.html" />
<link rel="alternate" hreflang="fr-fr" href="https://example.fr/product.html" />
<link rel="alternate" hreflang="x-default" href="https://example.com/product.html" />
The x-default tag specifies the fallback page for users whose language does not match any of the listed alternatives.
Each page that has translations must include hreflang tags pointing to all its language versions, including itself. Search engines use these reciprocal links to associate pages across store views.
Store View to Language Mapping
Each Magento store view corresponds to one hreflang language-region code. The mapping is based on the store view's locale setting (Stores → Configuration → General → General → Locale Options).
| Store View | Locale | Hreflang Code |
|---|---|---|
| English (US) | en_US | en-us |
| German | de_DE | de-de |
| French | fr_FR | fr-fr |
| Spanish (Mexico) | es_MX | es-mx |
If you have a store view that serves as the default for a language without regional targeting, use just the language code (e.g., en, de, fr).
Products and Categories: Automatic Hreflang
For product and category pages, hreflang tags are generated automatically when:
- Multiple store views exist and share the same product/category
- The SEO extension is configured to output hreflang tags
- The product or category is enabled in all relevant store views
No manual configuration is needed for products and categories. Magento recognizes that the same product entity exists across store views and generates the appropriate hreflang links.
CMS Pages: Manual Configuration Required
CMS pages, including the homepage, require manual hreflang setup. Magento treats CMS pages as independent entities -- even if two CMS pages have the same URL key in different store views, Magento does not automatically assume they are translations of each other.
Configuring Hreflang for CMS Pages
- Go to Content → Pages
- Open the CMS page (e.g., the English homepage)
- Navigate to the Alternate Settings section (sometimes labeled "Alternate Group")
- Link the corresponding CMS pages from other store views
Repeat this for each language version. Every CMS page in the group should reference all other pages in the group.
Homepage
The homepage is a CMS page and follows the same manual process. This is commonly overlooked -- if your homepage does not have hreflang tags, search engines may show the wrong language version in search results for your brand queries.
Verify homepage hreflang is configured by viewing the page source and checking for <link rel="alternate" hreflang="..."> tags.
Verification
Browser Check
View the page source (Ctrl+U) and search for "hreflang". Every page should list all its language alternatives plus an x-default entry.
Google Search Console
In Google Search Console → Enhancements → International targeting, Google reports hreflang errors such as:
- Return tags not found: Page A references page B, but page B does not reference page A back
- Unknown language code: Invalid hreflang code format
- No return tag: One-way hreflang links (must be reciprocal)
Common Issues
- Missing hreflang on CMS pages (not configured in Alternate Settings)
- Homepage missing hreflang (most common oversight)
- Non-reciprocal links (page A points to page B, but B does not point back to A)
- Incorrect locale codes (using
en_USinstead ofen-us)
Post-Configuration Steps
After setting up hreflang tags:
- Regenerate sitemaps: Sitemaps should include hreflang annotations for search engines that read sitemap-based hreflang
- Submit updated sitemaps to Google Search Console
- Wait for re-crawl: Google may take days to weeks to process hreflang changes
See also: How to Generate and Configure XML Sitemap in Magento 2