What hreflang actually does
A page with hreflang markup lists a set of alternate URLs, each tagged with a language code (and optionally a region, like es vs es-MX) plus a special x-default entry for visitors who don't match any listed language. Search engines use this to serve the right language version of your site to the right searcher, and to avoid treating your translated pages as duplicate content of each other.
Every page in the cluster needs to reference every other page in the cluster, including itself - a common source of errors is a one-way link (page A points to page B, but B doesn't point back to A).
Why it matters during a platform migration
If your store operates in multiple languages, a migration is exactly the moment hreflang tends to break - URL structures change per locale, and it's easy for the new platform's language-switching mechanism to not automatically wire up correct hreflang clusters for every route, especially routes that don't have a live translation yet. An incomplete or inconsistent hreflang setup can cause the wrong language version to rank in the wrong country, or dilute ranking signal across near-duplicate localized pages.
Hreflang should be verified for every URL pattern in the new IA, not just the homepage - product pages, category pages, and any content pages all need it if they're multilingual.
Common mistakes
The most frequent issues are missing return links (A links to B, B doesn't link back), pointing hreflang at a URL that returns a redirect or a 404 instead of the live page, and using the wrong language/region code format. None of these usually cause an outright penalty, but they do mean search engines may not honor the signal at all, defeating the point of adding it.
Frequently asked questions
Is hreflang the same as a language switcher on my site?
No - a language switcher is a UI element for visitors; hreflang is a signal for search engines, usually invisible to visitors, that lives in the page's HTML head, an HTTP header, or the sitemap. A site can have one without the other, though having both is standard practice.
Do I need an x-default entry?
It's recommended if you have a fallback page for visitors whose language/region doesn't match any of your specific versions - commonly this points at your default-language page.
Does hreflang affect my search ranking directly?
It doesn't act as a ranking boost - it affects which of your pages shows up for searchers in a given language/region, and helps prevent your translated pages from being treated as unwanted duplicates of each other.
Can hreflang be set in the sitemap instead of on the page?
Yes, both are valid per search engine documentation - some sites prefer sitemap-based hreflang because it's easier to generate and validate programmatically for a large number of URLs, which is the approach we generally use on migrated sites.