Hreflang in CMS systems: The Complete 2026 Guide

Implementing hreflang correctly inside a CMS requires understanding how each platform handles language variants, URL routing, and metadata generation. A misconfigured CMS plugin can inject broken hreflang markup across thousands of pages. This guide covers hreflang implementation in four major...

Introduction

1. WordPress: plugins and custom solutions

WordPress supports hreflang through several plugins, but not all produce valid markup. The three most reliable approaches in 2026 are:

Polylang Pro generates <link> hreflang tags for each language variant and includes self-referential markup. It also adds <xhtml:link> entries in XML sitemaps. Verify that the "Hide URL language information for default language" setting is disabled if you use subdirectory paths.

WPML outputs hreflang via its wpml_hreflang filter and the &hreflang=1 URL parameter on sitemaps. WPML versions 4.6+ include a hreflang validation tool in the admin dashboard. Common WPML issues include missing return tags when a translation is in draft status and incorrect hreflang language codes for regional variants (e.g., en instead of en-US).

Custom implementation: A functions.php filter on wp_head can output hreflang links by reading a custom field per page. This gives full control but requires maintaining URL consistency across languages. Always validate WordPress hreflang output with a dedicated validator before launch (WPML Team, 2025).

2. Shopify: limitations and solutions

Shopify's built-in internationalization supports markets per country or language. The platform automatically generates hreflang tags for each market, but has notable limitations. Shopify only supports hreflang for markets created inside the Shopify admin; custom subdirectory setups produce no hreflang markup. Its hreflang output is hardcoded into the theme's <head> via {{ content_for_header }} and cannot be modified through Liquid alone. Shopify also does not output hreflang in XML sitemaps. For stores exceeding 20 markets, consider a headless Shopify architecture where hreflang is managed at the CDN or reverse proxy layer (Shopify Help Center, 2025).

3. Sanity (headless CMS)

Sanity provides locale-aware content through its structured content model. For single-document locale fields, query translation references and output <link> tags at build time using sanity-plugin-internationalization. For separate documents per locale, generate sitemaps with <xhtml:link> entries by joining documents on a shared translation ID. Sanity's GROQ queries can fetch all translation slugs in one pass. The key risk is stale hreflang references when a translation is deleted but the reference remains (Sanity Documentation, 2026).

4. Contentful (headless CMS)

Contentful's localization model maps each entry to a locale with a translation reference field linking variants. Include this field in your GraphQL or REST query, map each linked entry's slug and locale code to hreflang tags, and iterate over entries to build <xhtml:link> clusters for sitemaps. Contentful's 2025 release added a "localized slug" field type that validates uniqueness per locale (Contentful Documentation, 2025).

5. Proxy-level hreflang generation

For any headless CMS, consider generating hreflang at the reverse proxy layer. This approach reads the Content-Language header or response body from the CMS API, injects <link> hreflang tags into the HTML response using edge-side includes (ESI), and generates XML sitemaps with hreflang annotations via a scheduled serverless function. This decouples hreflang logic from the CMS, making it easier to maintain consistency across multiple CMS backends during a migration (Hreflang.org, 2025).

Audit checklist

[ ] CMS plugin or implementation produces self-referential markup on every page.
[ ] No draft or unpublished translation breaks the hreflang cluster.
[ ] Shopify markets created for all target regions; hreflang verified in template output.
[ ] Headless CMS queries include translation references in hreflang generation.
[ ] XML sitemaps contain <xhtml:link> entries for all language-region pairs.
[ ] Proxy-level hreflang tested for injection correctness.

Conclusion

Hreflang implementation varies significantly across CMS platforms. WordPress and Shopify require plugin-level validation, while headless CMS platforms like Sanity and Contentful demand custom query patterns. Whichever platform you use, validate every hreflang cluster with an automated tool and...

Ready to Build Your Dream Website?

Let's discuss your project and create something amazing together.