Installation

Chapters of this Documentation

Requirements

TYPO3 v13.4 LTS or v14.3 LTS
PHP 8.2 or higher—composer.json requires ^8.2 and the CI matrix covers 8.2 through 8.5. Neither composer.json nor ext_emconf.php declares a PHP constraint, so this is a tested range rather than an enforced one
The system extensions info and seo—pulled in automatically as dependencies

Before you install, check When This Applies. If all your languages live in one page tree, TYPO3 already renders correct hreflang tags and this extension adds nothing.

1. Install the Package

composer require b13/hreflang-multisite

2. Add the Configuration

There are two ways in, and they differ only in where the defaults come from.

With Site Sets (Recommended)

The extension ships a site set named b13/hreflang-multisite. Add it to your site’s config.yaml:

dependencies:
  - b13/hreflang-multisite

That brings the defaults. You then only add your own rootpage-sets on top.

Without Site Sets

Include the shipped PageTsConfig manually—it is not loaded automatically:

@import 'EXT:hreflang_multisite/Configuration/TSConfig/PageTsConfig.typoscript'

Or set every option yourself; see The Complete Block.

Put the configuration in a file and include it on every root page, so the root pages of one group cannot drift apart.

3. Define at Least One Group

plugin.tx_hreflang_multisite.rootpage-sets {
    10 = 1,13
    20 = 11,31
}

Nothing works until this exists. Without a group, the page set field is hidden from the page properties and no set can be created.

Each key defines one group of root pages that may be linked together. A root page that appears in no group cannot be linked at all.

4. Decide Where Records Are Stored

plugin.tx_hreflang_multisite.storagePid = 98

If unset, page set records are stored on the page currently being edited. The records are hidden from the list module either way, so this decides where they live, not whether editors see them.

5. Turn On the Configuration Check

plugin.tx_hreflang_multisite.debug = 1

Despite the name this is not a developer switch. It is the only backend surface that surfaces duplicate hreflang codes across a root page group, and it defaults to 0. See Verifying a Setup.

Going Live

rootpage-sets defines every group that editors need
The configuration is included on all root pages, not just one
Language and region codes are unique inside each group—the check under debug reports duplicates
Every set has an x-default and it points at a page inside the set
debug is set to 1 if editors should see the check
Check the rendered <link rel="alternate"> tags on a real page, on one page per root page. This is the only step that shows what visitors and search engines actually get. Expect one tag per language and region in the set, plus x-default as the last entry