README

Magento 2 Hreflang Extension: Multi-Language and Multi-Region Link Tags (Hyva + Luma)

Tell search engines exactly which page to show for each language and region. Panth Hreflang adds admin-managed hreflang groups that pair product, category, and CMS pages across store views. It emits the correct <link rel="alternate" hreflang> tags in the <head> on every request, including an automatic x-default. Works on Hyva and Luma with no template overrides needed.

Product page: kishansavaliya.com/magento-2-hreflang.html

Quick Answer

What is Panth Hreflang? It is a Magento 2 hreflang extension that adds <link rel="alternate" hreflang> tags to every storefront page so search engines know which localized version to show to each shopper.

What does it add to my store?

Admin hreflang groups that link the same product, category, or CMS page across multiple store views with the correct locale code and URL.
Automatic x-default so every page always declares a fallback for users whose locale does not match any group entry.
Locale fallback that reads each store's general/locale/code when you leave the Locale field blank, so basic setups need almost no manual entry.
URL auto-resolution from url_rewrite on save, so you do not have to copy URLs by hand.
A self-diagnostic panel on the config page that flags common misconfigurations before they reach production.

Which themes are supported? Both Hyva and Luma, and any other theme. The rendering is a plain PHP head block with no Alpine.js, RequireJS, or Knockout code.

What does it need? Magento 2.4.4 to 2.4.8, PHP 8.1 to 8.4, and the free mage2kishan/module-core package.

Need Custom Magento 2 Development?

Get a free quote for your project in 24 hours for custom modules, Hyva themes, performance work, M1 to M2 migrations, and Adobe Commerce Cloud.

Kishan Savaliya

Top Rated Plus on Upwork

100% Job Success • 10+ Years Magento Experience Adobe Certified • Hyva Specialist

Panth Infotech Agency

Magento Development Team

Custom Modules • Theme Design • Migrations Performance • SEO • Adobe Commerce Cloud

Visit our website: kishansavaliya.com | Get a quote: kishansavaliya.com/get-quote

Who Is It For
Key Features
Screenshots
Compatibility
Installation
Configuration
How It Works
Managing Hreflang Groups
FAQ
Support
About Panth Infotech
Quick Links

Who Is It For

Multi-language stores that run separate store views for each locale and want search engines to serve the right version to each shopper.
Multi-region stores that sell the same products in different countries with different currencies or pricing and need region-specific hreflang tags.
Hyva storefronts that need hreflang without adding any Alpine.js or RequireJS overhead, since the rendering is pure PHP.
Merchants running several brands on one Magento install who need per-website scope control to stop brands cross-linking to each other.
SEO teams who want a diagnostic panel in the admin to catch misconfigured groups before they go live.

Key Features

Admin Hreflang Groups

Create groups that link a product, category, or CMS page across as many store views as you need.
Active flag per group so you can stage hreflang changes or pull back a bad mapping without deleting the data.
Group code and notes fields so your team can document why a specific mapping was created.
Browse Products, Browse Categories, and Browse CMS Pages modals on the edit form to look up entity IDs by name without leaving the page.
Mass delete from the grid to clean up old groups in bulk.

Member Configuration

One member row per store view, each carrying its own Store View, Entity ID, Locale, URL, and Is Default toggle.
Locale fallback reads the store's general/locale/code and converts it to BCP 47 format when the Locale field is left blank.
URL auto-resolution looks up url_rewrite for the entity and store on save, so you do not have to paste URLs manually.
Is Default flag controls which member URL is emitted as x-default.

Automatic x-default

Every group-matched page gets an x-default alternate pointing to the flagged default member.
Unmatched pages on single-locale installs still get a self-referencing x-default, so the page always declares its intent to search engines.
Configurable - turn x-default emission off per store view if you prefer locale-only tags.

CMS Page Matching

Three strategies for matching CMS pages across stores: by URL key (default, matches pages sharing the same identifier), by page ID, or by manual group entry.
Per-store-view config so different parts of the site can use different strategies.
Home page detection handles the Magento admin "Default Pages" picker format, which appends a page ID suffix to the identifier.

Scope Control

Website scope (default) limits alternates to stores within the same website, so two independent brands on one install do not cross-link.
Global scope includes every active storefront store across all websites.

Configuration Diagnostic

Five automated checks run every time the config page loads: x-default coverage, group size, store locale setup, locale conflicts inside groups, and hreflang-enabled status of each member store.
Errors and warnings surfaced inline so problems are visible before you deploy.

Theme-Agnostic Rendering

Plain PHP head block attached via default.xml layout, so the same tags render on Hyva, Luma, and any custom theme.
No Alpine.js, no RequireJS, no Knockout involved in rendering.
Full Page Cache friendly since the head block is cacheable.

Built to Last

Constructor dependency injection only, no ObjectManager calls.
Translation ready, every label uses Magento's __() function.
Multi-store aware, settings respect default, website, and store view scope.

Screenshots

Hero Banner

Admin Configuration

Hreflang Mapping Grid

Edit Hreflang Group Form

Demo

Compatibility

Requirement	Versions Supported
Magento Open Source	2.4.4, 2.4.5, 2.4.6, 2.4.7, 2.4.8
Adobe Commerce	2.4.4, 2.4.5, 2.4.6, 2.4.7, 2.4.8
Adobe Commerce Cloud	2.4.4 to 2.4.8
PHP	8.1.x, 8.2.x, 8.3.x, 8.4.x
Hyva Theme	1.0+ (no template overrides needed)
Luma Theme	Native support
Required Dependency	`mage2kishan/module-core` (free)

Installation

Composer Installation (Recommended)

composer require mage2kishan/module-hreflang
bin/magento module:enable Panth_Core Panth_Hreflang
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Manual Installation via ZIP

Download the latest release from Packagist or from the product page.
Extract it to app/code/Panth/Hreflang/ in your Magento install.
Make sure Panth_Core is installed too (required dependency).
Run the commands above starting from bin/magento module:enable.

Verify Installation

bin/magento module:status Panth_Hreflang
# Expected: Module is enabled

After install, open:

Admin → Panth Infotech → Hreflang → Hreflang Mapping
Admin → Stores → Configuration → Panth Infotech → Hreflang

Configuration

Go to Stores → Configuration → Panth Infotech → Hreflang.

Setting	Group	Default	Description
Enabled	Hreflang	Yes	Master switch at store-view scope. When off, no `<link rel="alternate">` tags are emitted for that store.
Emit x-default	Hreflang	Yes	When on, every group with two or more distinct locales also emits an `hreflang="x-default"` tag pointing at the Is Default member.
Hreflang Scope	Hreflang	Within Same Website	Controls whether alternates are restricted to stores in the same website (`website`) or include every active storefront store (`global`).
CMS Page Relation Method	Hreflang	Same URL Key	How CMS pages are matched across stores: by URL key (auto, default), by page ID (auto), or by manual group entry.
Configuration Diagnostic	Hreflang	(read-only panel)	Runs five automated checks and shows the results inline. Refresh by saving configuration.

How It Works

view/frontend/layout/default.xml attaches a cacheable head block to head.additional on every storefront page.
The template calls the ViewModel\Hreflang which detects the current entity (product via registry, category via registry, CMS page via action name and request params).
The ViewModel calls Model\Hreflang\Resolver with the entity type, entity ID, and current store ID.
The resolver checks scope, finds the active group for the entity, loads all member rows within scope, deduplicates by locale, and returns an array of {locale, url, is_default} rows.
The template walks the array and emits one <link rel="alternate" hreflang="..." href="..."/> tag per row, plus the x-default tag when configured.
If no group matches the current page, a single self-referencing x-default tag is emitted so the page always has a fallback declaration.
Controller\Adminhtml\Hreflang\Save handles writes: it saves the group row, then reconciles the submitted member rows against the database, inserting new ones, updating changed ones, and deleting removed ones. Blank Locale and URL fields are resolved at save time.
Controller\Adminhtml\Hreflang\EntitySearch backs the Browse modals on the edit form, returning up to 50 matching entity records as JSON for a given search term and store.

Managing Hreflang Groups

Open Admin → Panth Infotech → Hreflang → Hreflang Mapping.

Group Fields

Field	Description
Entity Type	`product`, `category`, or `cms_page`. Set once per group. All member rows are treated as this type on save.
Group Code	Admin-only label. Not shown on the storefront. Use it to identify groups in the grid, for example `tops_us_uk`.
Notes	Free text. Record why a mapping was created so future admins have context.
Active	Deactivating a group immediately hides its tags on the next request. The data stays in the database.

Member Fields

Field	Description
Store View	One row per store view that participates in the group.
Entity ID	The entity's numeric ID on that store view. IDs can differ across stores for the same product.
Locale	Optional BCP 47 locale (e.g. `en-GB`). Leave blank to use the store's Magento locale automatically.
URL	Optional absolute URL. Leave blank to auto-resolve from `url_rewrite` on save.
Is Default	Flag exactly one row per group. That row's URL becomes the `x-default` alternate.

FAQ

Does Panth Hreflang work on Hyva themes?

Yes. The head block is plain PHP with no Alpine.js, RequireJS, or Knockout code. The same template renders identically on Hyva and Luma.

Does Magento 2 emit hreflang tags out of the box?

No. The core Magento_Store module does not emit <link rel="alternate" hreflang> tags on any page type. Without a module like Panth Hreflang, Google treats your localized store views as duplicate content and picks one version to index arbitrarily.

What happens on a single-locale install?

The module still emits a self-referencing x-default tag on every page. This tells search engines the page's canonical URL and does not cause duplicate-content issues.

Can I set up hreflang for just products and skip categories?

Yes. Each group has its own Entity Type. Create product groups only and leave categories ungrouped. Those category pages will just emit the self-referencing x-default fallback.

What happens if two stores in a group share the same locale?

The resolver detects fewer than two distinct locales and returns an empty alternate list. The ViewModel falls back to a clean self-referencing x-default. Assign different locale codes to differentiate the stores, or override the Locale field on the member rows.

Do I need to update groups after renaming a product URL key?

Yes. Member rows store the absolute URL resolved at save time. Renaming a URL key updates url_rewrite but does not re-walk hreflang groups automatically. Open the affected group and save it again to refresh the resolved URLs.

Can I hide the `x-default` tag?

Yes. Set Emit x-default to No in the configuration. Only locale-specific tags are emitted then. The self-referencing fallback on unmatched pages is also suppressed.

Does it work with CMS pages that have different identifiers across stores?

Yes. Set the CMS Page Relation Method to By Identifier (manual group) and create a manual hreflang group of type cms_page with one member row per store. The by_url_key and by_id automatic methods work when pages share the same identifier or page ID across stores.

Does Panth Hreflang need Panth Core?

Yes. mage2kishan/module-core is a free, required dependency that Composer installs for you automatically.

Support

Channel	Contact
Product Page	kishansavaliya.com/magento-2-hreflang.html
Email	kishansavaliyakb@gmail.com
Website	kishansavaliya.com
WhatsApp	+91 84012 70422
GitHub Issues	github.com/mage2sk/module-hreflang/issues
Upwork (Top Rated Plus)	Hire Kishan Savaliya
Upwork Agency	Panth Infotech

Response time: 1-2 business days.

Need Custom Magento Development?

Looking for custom Magento module development, Hyva theme work, store migrations, or performance tuning? Get a free quote in 24 hours:

About Panth Infotech

Built and maintained by Kishan Savaliya (kishansavaliya.com), a Top Rated Plus Magento developer on Upwork with 10+ years of eCommerce experience.

Panth Infotech is a Magento 2 development agency that builds high quality, security focused extensions and themes for both Hyva and Luma storefronts. The extension suite covers SEO, performance, checkout, product presentation, customer engagement, and store management, with each module built to MEQP standards and tested across Magento 2.4.4 to 2.4.8.

Browse the full extension catalog on our Magento extensions page or on Packagist.

Quick Links

Resource	Link
Product Page	magento-2-hreflang.html
Packagist	mage2kishan/module-hreflang
GitHub	mage2sk/module-hreflang
Website	kishansavaliya.com
Free Quote	kishansavaliya.com/get-quote
Upwork (Top Rated Plus)	Hire Kishan Savaliya
Upwork Agency	Panth Infotech
Email	kishansavaliyakb@gmail.com
WhatsApp	+91 84012 70422

Ready to help search engines serve the right store view to each shopper?

SEO Keywords: magento 2 hreflang, magento 2 hreflang extension, magento 2 hreflang module, magento 2 multi-language seo, magento 2 multi-region seo, magento 2 x-default, magento 2 hreflang tags, magento 2 cross-store hreflang, magento 2 hreflang products, magento 2 hreflang categories, magento 2 hreflang cms pages, hyva hreflang, hyva hreflang extension, luma hreflang, magento 2 international seo, magento 2 alternate link tags, magento 2 localization seo, magento 2 hreflang x-default, magento 2 multi-store hreflang, magento 2.4.8 hreflang, php 8.4 hreflang, mage2kishan hreflang, panth hreflang, panth infotech, hire magento developer, top rated plus upwork, kishan savaliya magento, custom magento development, magento 2 seo extension

mage2kishan/module-hreflang

包简介

关键字：

README 文档