Configure CMS pages with the Href-Lang

Products and categories have built-in parent-child relationships across store views:

• Same product ID in multiple stores = automatic connection
• Product in EN store and FR store with same ID = translations
• Module automatically generates hreflang tags

CMS pages are independent per store view:

• No automatic relationship between pages
• Homepage in EN store ≠ homepage in FR store (from Magento's perspective)
• "About Us" page has no link to French "À Propos" page
• You must manually group them

1. All pages in the same category link to each other with hreflang tags
2. Pages in different categories don't link to each other
3. Ungrouped pages (no category) have no hreflang tags

Think of it like: "These pages are the same content, just in different languages"

You have these CMS pages:

• about-us (English store)
• a-propos (French store)
• uber-uns (German store)

Step 1: Edit English Page

Navigate to: Content → Pages → About Us

1. Scroll to Alternate Language Settings
2. Click New Category field
3. Enter: about-page
4. Save page

Step 2: Edit French Page

Navigate to: Content → Pages → À Propos

1. Scroll to Alternate Language Settings
2. Select dropdown: about-page (now available)
3. Save page

Step 3: Edit German Page

Navigate to: Content → Pages → Über Uns

1. Scroll to Alternate Language Settings
2. Select dropdown: about-page
3. Save page

Result:

All three pages now have hreflang tags:

<!-- On English page -→
<link rel="alternate" hreflang="en-us" href="https://example.com/about-us" />
<link rel="alternate" hreflang="fr-fr" href="https://example.fr/a-propos" />
<link rel="alternate" hreflang="de-de" href="https://example.de/uber-uns" />

Step 1: Edit Homepage (English store)

Navigate to: Content → Pages → Home Page (in English store view)

1. Scroll to Alternate Language Settings
2. New Category: homepage
3. Save

Step 2: Edit Homepage (French store)

Switch to French store view, then:

Navigate to: Content → Pages → Page d'accueil (in French store view)

1. Scroll to Alternate Language Settings
2. Select: homepage
3. Save

Step 3: Repeat for other stores

Each store's homepage → select homepage category

Result:

<link rel="alternate" hreflang="en-us" href="https://example.com/" />
<link rel="alternate" hreflang="fr-fr" href="https://example.fr/" />
<link rel="alternate" hreflang="de-de" href="https://example.de/" />

Pages to group:

• Homepage in all languages → category: homepage
• About page in all languages → category: about-page
• Contact page in all languages → category: contact-page
• Privacy policy in all languages → category: privacy-page

Setup:

Category: homepage
├── Home (EN) - example.com/  
├── Accueil (FR) - example.fr/  
└── Startseite (DE) - example.de/

Category: about-page
├── About Us (EN) - example.com/about-us  
├── À Propos (FR) - example.fr/a-propos  
└── Über Uns (DE) - example.de/uber-uns

Category: contact-page
├── Contact (EN) - example.com/contact  
├── Contact (FR) - example.fr/contact  
└── Kontakt (DE) - example.de/kontakt

Some pages only exist in certain languages.

Example: Legal pages that differ by country

Category: privacy-eu
├── Privacy Policy (EN-GB) - example.co.uk/privacy  
├── Politique de confidentialité (FR) - example.fr/confidentialite  
└── Datenschutz (DE) - example.de/datenschutz

Category: privacy-us
└── Privacy Policy (EN-US) - example.com/privacy
(No other languages - US-specific content)

Category: terms-eu
├── Terms & Conditions (EN-GB) - example.co.uk/terms  
├── Conditions Générales (FR) - example.fr/conditions  
└── AGB (DE) - example.de/agb

Important: Don't link EU privacy pages to US privacy pages if the content differs significantly.

Campaign in multiple markets:

Category: summer-sale-2024
├── Summer Sale (EN-US) - example.com/summer-sale  
├── Soldes d'été (FR-FR) - example.fr/soldes-ete  
├── Sommerschlussverkauf (DE-DE) - example.de/sommer-sale  
└── Summer Sale (EN-GB) - example.co.uk/summer-sale

All pages promote same sale, different languages → group together.

✅ Descriptive and unique:

• homepage
• about-page
• shipping-info
• return-policy
• faq-general

✅ Include campaign/year if temporary:

• black-friday-2024
• spring-sale-2024

✅ Use store/region if content differs:

• privacy-eu
• privacy-us
• terms-b2b
• terms-b2c

❌ Too generic:

• page1
• cms
• group-a

❌ Language-specific:

• about-us-english (category is for ALL languages)
• french-pages

Why: Category name is internal only. Use it to identify which pages belong together, not which language they are.

1. Enable debug mode in module configuration
2. Visit CMS page with ?show-alternate=1

   https://example.com/about-us?show-alternate=1
   

3. Verify hreflang tags appear
4. Check all grouped pages are listed

Visit homepage with debug parameter:

https://example.com/?show-alternate=1

Check output shows all store homepages.

Problem: Tags not appearing

Check:

• CMS Pages enabled in module configuration
• All pages in group have same category name
• Pages assigned to correct store views
• Cache cleared after changes

Problem: Wrong pages grouped together

Check:

• Category spelling is exactly the same
• Not confusing similar page types (e.g., "Terms B2B" vs "Terms B2C")

1. Create category naming scheme first:

   • List all CMS page types
   • Define category name for each type
   • Document in spreadsheet

2. Update in batches:

   • Group by page type (all "About" pages first)
   • Create category on first page
   • Apply same category to translations

3. Use consistent naming:

   • homepage not home-page or home_page
   • Stick to one format project-wide

Common pages on most sites:

homepage          → All homepage variations
about-page        → About Us pages
contact-page      → Contact pages
shipping-info     → Shipping information
return-policy     → Return/refund policies
privacy-page      → Privacy policies
terms-page        → Terms & conditions
faq-general       → General FAQ pages

CMS pages must be assigned to correct store views:

• English "About Us" → assigned to English store
• French "À Propos" → assigned to French store
• Don't assign same page to multiple stores (defeats the purpose)

Each page should have appropriate URL for its language:

• ✅ about-us (English)
• ✅ a-propos (French)
• ❌ about-us (used in all stores)

Pages without a category simply won't have hreflang tags:

• Single-store sites don't need it
• Store-specific pages (no translations) don't need it
• Only group pages that are true translations

Run module self-test:

1. Admin → Magmodules → Alternate Hreflang → Developer → Self-Test
2. Check CMS Pages section
3. Verify grouped pages detected

No admin overview of categories exists. To audit:

1. Export CMS pages with categories (custom SQL or export)
2. Review which pages share categories
3. Verify groupings are correct

SQL to list categories:

SELECT
    cms_page.title,
    cms_page.identifier,
    cms_page.alternate_category
FROM cms_page
WHERE cms_page.alternate_category IS NOT NULL
ORDER BY cms_page.alternate_category, cms_page.title;