PrestaShop hreflang: language mappings and validation
Check PrestaShop hreflang output, reciprocal language mappings, regional URLs and optional x-default. Verify module and sitemap output together.
Check the language URLs your shop publishes before changing hreflang. Use accurate page mappings, a clear output owner and repeatable validation for every participating language cluster.
What we would do
We would identify the cause of a wrong or missing alternate before choosing a module. The route depends on your existing theme, SEO modules, integrations that import translations or change URLs, catalogue mappings, markets and the team maintaining them. Record which pages should be equivalents and which component currently publishes that relationship.
Make the change on a staging copy of that setup. Keep staging private and out of search, rehearse the mapping and output checks, and save the previous settings and templates. Agree a switch window and rollback steps, then check the public pages after deployment. Staging checks prove the structure; final production hosts and indexability still need checking on live pages. Never publish staging URLs in live alternates or sitemaps.
If multilingual routing, canonicals and alternate mappings conflict, the PrestaShop SEO Audit & Action Plan provides a review and prioritised fixes for your developer; implementation is separate.
Understand what hreflang does
Hreflang identifies equivalent language or regional versions of a page. It helps search engines choose an appropriate version; it does not translate content, force rankings or combine translated pages into one canonical page.
Fully translated main content is not duplicate content merely because it is translated. Copied source-language text and same-language regional duplication need their own content/canonical review. Use separate language URLs and let people switch explicitly. See Google's multilingual-site guidance.
Hreflang is recommended when you need that relationship expressed, not compulsory for every multilingual shop. Google can discover language versions without it. Poor content, missing translations, blocked URLs and confusing routing are separate problems.
Inspect native PrestaShop output first
Modern PrestaShop builds an alternate-language URL map for active languages in the current shop. In PrestaShop 9, the map is keyed by language_code and uses Link::getLanguageLink(). The theme must actually render it in the head. An overridden head partial can remove or duplicate it.
Classic and Hummingbird provide modern theme integrations, but verify the installed releases. Classic remained the default in 9.0; Hummingbird became the default in 9.1. PrestaShop 1.6's default-bootstrap header does not provide the same modern alternate block. Do not assume identical output across these generations.
The language's ISO code participates in URL routing, while language_code supplies the native alternate-map key. Locale is a separate field. Fix wrong values in their actual configuration, then check rendered output; changing one does not guarantee the other is correct.
Shop URLs belong to shops, not individual languages. Subfolders can use native multilingual routing. Separate language domains or subdomains need suitable multistore or custom routing. Native single-shop language links do not automatically discover equivalent products on unrelated shop domains.
On releases using these menu labels, inspect International → Localization → Languages for language fields and Shop Parameters → Traffic & SEO → SEO & URLs for URL settings. Set shop URL concerns the shop address. Record the current shop context and values before editing; changing an established language path also needs a redirect and internal-link plan.
Build reciprocal page clusters
Use valid language codes, optionally with a supported region: en-GB, not en-UK; cs for Czech, not cz. Point to the actual equivalent page using its full URL. Each participating version should identify itself and return links to its partners. Google can process reciprocal subsets; a missing annotation elsewhere does not invalidate every working pair. See Google's alternate-version rules.
For an English/German/French product cluster, the same participating set belongs in each page's head:
<link rel="alternate" hreflang="en" href="https://store.example/en/product">
<link rel="alternate" hreflang="de" href="https://store.example/de/produkt">
<link rel="alternate" hreflang="fr" href="https://store.example/fr/produit">x-default is an optional fallback, for example a language selector or chosen general version. Its absence does not make the language set invalid. If you use it, keep the destination suitable and accessible. See Google's x-default explanation.
<link rel="alternate" hreflang="x-default" href="https://store.example/en/product">Keep the usual canonical for each genuinely translated version in that language. Resolve unexpected redirects, noindex, errors or conflicting canonicals before relying on the cluster. Hreflang does not make an ineligible destination indexable.
For regional shops, map equivalent entities explicitly. Matching numeric IDs across stores are safe only when they represent the same item or content. Decide which destination owns each language/region code if several shops offer it. Never map an untranslated product to a homepage merely to fill a slot.
HTML head tags and XML sitemap annotations can express these relationships. If you use both, keep their mappings consistent. A sitemap entry should include the current URL and the relevant alternate references with the required XML namespaces; inspect all participating entries rather than adding only a one-way foreign link.
Work through a regional mapping error
Your UK and US shops sell the same lamp in English, but catalogue imports created different product records. A mapping based on matching numeric IDs links the UK lamp to a US lampshade. The en-GB and en-US codes can be valid while the relationship is wrong.
Confirm the equivalent using a stable catalogue reference and the actual product content, correct the mapping, then inspect both destinations and their return links. If the US lamp is not published, remove its alternate entry from the participating pages and enabled sitemap annotations until it is ready. Add this case to checks after catalogue imports: a crawler can flag broken relationships without recognising that two valid pages sell different items.
Choose one implementation and keep setup in module help
| What you find | Starting choice | Evidence before switching |
|---|---|---|
| Native output covers your shop's language URLs. | Keep it and maintain the language configuration. | Representative equivalent pages have usable, reciprocal sets. |
| A custom theme has removed the alternate block. | Restore its rendering of the native map where that map meets your needs. | The repaired head contains the intended set without duplicate output. |
| You need cross-shop mappings, exclusions or page-specific exceptions. | Assess an additional implementation against those requirements. | The installed release supports your entities and destinations, including return links. |
| Different generators publish conflicting sets. | Choose the output owner and disable the competing output through its supported controls. | Cached public responses and any enabled sitemap annotations agree. |
Choose one owner for each page's alternate set and check its integration with the actual theme output.
For automatic multistore connections, Local/Shared manual groups, source/destination rows, exclusions, draft previews, ownership and licensing requirements, follow the Hreflang Tags Manager help page.
For hreflang settings, URL patterns, previews, URL-history redirects and generated language sitemaps, follow the SEO Revolution help page.
Hreflang Tags Manager covers supported entity pages and omits its generated sets for search, filtered results and listing pages after page one. On successful responses, account, checkout and module pages keep any alternates supplied by their own controllers and theme. Manual claims take precedence over automatic connections. Custom URL destinations and dynamic mappings still need return-link checks. Canonical handling remains a separate concern.
When SEO Revolution owns hreflang output, the standalone manager stays silent. The suite needs at least two eligible alternates, including the current page; its x-default output depends on the selected default URL remaining eligible. Its code prefers language_code and can fall back to locale. Header and sitemap features have their own controls and eligibility checks. Repeat the output checks after theme changes, because module-generated tags still depend on the theme’s integration.
Validate the actual pages after changes
- Choose one real product with completed translations. Fetch the HTML response or use View Source, then inspect the head for alternate links. Check which component supplies them.
- Open every target. Confirm the final URL, visible language, response status, robots directive and canonical. Check the actual language/region code against the intended audience.
- Compare the sets. Verify self-references and return links for participating pages. Treat x-default as optional, and validate its target when present.
- Repeat for the homepage, categories, CMS, brands and suppliers where they participate. A module's intentionally unsupported page types do not require invented mappings.
- Inspect generated XML if sitemap annotations are enabled. Compare its URLs with head tags and language-selector destinations.
- Use a crawler across the intended URL inventory to find invalid codes, redirects, one-way pairs, duplicate output and ineligible targets. Record exceptions rather than assuming every page must participate.
- Repeat after changing domains, language settings, slugs, theme head templates, SEO ownership or sitemap generation.
Missing or unusable annotations can be ignored or fail to establish a relationship. Check which mappings are affected and correct the unusable annotations.
If an old destination survives a correction, compare a refreshed response with cached HTML and identify the cache layer before editing more mappings. Clearing your browser cache does not clear server or CDN HTML. If tags are missing, compare the same page type in the installed theme and its head override before assuming the language data is absent.
For the content and currency preparation behind these URLs, use the translations and international selling guide.
Plan the switch and handover
- Save before-and-after HTML and mapping settings for the agreed test pages, including an intentional exclusion. Keep the previous output configuration ready to restore.
- Deploy the approved settings and template changes together, refresh affected caches and regenerate enabled sitemaps. Repeat the validation above on public URLs before signing off.
- Give the person maintaining the shop the output owner, mapping rules, exclusions, test URLs and rollback instructions. Repeat the relevant checks when that person changes a language or imports catalogue data.
What to ask your developer or agency
- How are equivalent records matched across shops, and what happens when a translation is unpublished or an import replaces a record?
- Which theme override or module controls the head, and which settings control sitemap annotations?
- Who checks new language and domain changes, and what evidence will trigger rollback?
Questions owners ask
Do I need to move to separate domains to fix hreflang?
No. A working subfolder setup can express language alternatives. Choose domains for your market and shop architecture; moving established URLs adds migration work that a tag correction may not need.
Can hreflang replace the language selector or redirect visitors?
No. Keep a usable selector linking to the equivalent page. Automatic language or location redirects need separate review: they can prevent visitors and crawlers from reaching the URL they requested.
How soon will Google show the repaired version?
There is no fixed timetable. Keep the corrected HTML and crawl results as technical evidence; search results depend on recrawling and Google's selection. An unchanged ranking alone does not show whether an annotation is valid.