Using TYPO3 Site Handling for Clean Multi‑Site, Multi‑Language Projects

The problem with legacy multi‑site setup

In TYPO3 versions before v9, managing several domains or languages meant editing sys_domain records, adding TypoScript conditions, and maintaining separate RealURL configurations. Changes often required clearing caches and risked breaking links when a domain identifier was altered.

What Site Handling changes

Site Handling introduces a single YAML file per site under config/sites//config.yaml. The file defines base URLs, languages, error handling, and route enhancers. The site identifier is used by the router to generate absolute URLs, so templates no longer need hardcoded hostnames.

Worked example: two sites, three languages

Suppose we run a corporate site (example.com) and a blog (blog.example.com) with English, German and French. We create two folders:

• config/sites/example/config.yaml
• config/sites/blog/config.yaml

Example for the main site:

# config/sites/example/config.yaml
rootPageId: 1
base: 'https://example.com/'
baseVariants:
  -
    base: 'https://staging.example.com/'
    condition: 'applicationContext == "Development"'
languages:
  -
    title: English
    languageId: '0'
    locale: 'en_US.UTF-8'
    isoCode: 'en'
    hreflang: ''
    direction: ''
    flag: us
    languageIfEmpty: true
  -
    title: Deutsch
    languageId: '1'
    locale: 'de_DE.UTF-8'
    isoCode: 'de'
    hreflang: 'de-de'
    direction: ''
    flag: de
    languageIfEmpty: false
  -
    title: Français
    languageId: '2'
    locale: 'fr_FR.UTF-8'
    isoCode: 'fr'
    hreflang: 'fr-fr'
    direction: ''
    flag: fr
    languageIfEmpty: false
errorHandling:
  -
    errorCode: 404
    handler: Fluid
    options:
      templateFile: 'EXT:example_site/Resources/Private/Templates/Error/404.html'
routeEnhancers:
  NewsPlugin:
    type: Extbase
    limitToPages:
      - 2
    extension: News
    plugin: Pi1
    routes:
      -
        routePath: '/news/{news_title}'
        _controller: 'News::detail'
        _arguments:
          news_title: newsTitle
    aspect:
      newsTitle:
        type: PersistedAliasMapper
        tableName: tx_news_domain_model_news
        routeFieldName: path_segment

The blog site uses a similar file with a different base and its own rootPageId. After placing the files, clear the cache:

bin/typo3 cache:flush

You can verify that both sites are known:
bin/typo3 site:list

The output should list the identifiers example and blog with their base URLs. To test route generation for a news detail link:
bin/typo3 routing:generate example /news/my-first-article

If the route enhancer is correct, the command returns a full URL like https://example.com/news/my-first-article. In the frontend, view the page source of a German page and confirm the presence of hreflang="de-de" tags.
Trade‑offs and limits to watch
Site identifiers must stay unchanged; renaming a folder breaks existing links stored in the database and requires a search‑replace across content and configuration. Route enhancer configuration for Extbase plugins demands an exact match of the plugin’s namespace, controller and action names; a typo causes the enhancer to be ignored and the router falls back to the default page‑based route, which can be hard to notice because no error is logged. Language fallback chains only affect translated records; untranslated content still renders in the default language unless you set hideNonTranslatedContent in the TCA of the affected table. Finally, base variants apply only to the base URL and language base path; other settings such as error pages or route enhancers cannot be overridden per environment, so you may need separate site files or a deployment‑time templating step.
Getting started and verification
Begin by exporting your current sys_domain records into site identifiers, then create the YAML files as shown above. After committing the config/sites/ directory to version control, run the following checks in a fresh TYPO3 v12+ installation:

bin/typo3 site:list confirms identifier and base URL.
bin/typo3 routing:generate <site> <path> validates a custom enhancer.
Inspect the rendered HTML for hreflang tags to ensure language fallback works as expected.
Visit a non‑existing page to verify that the custom Fluid error template is used.

If any step fails, review the YAML for indentation errors or mismatched plugin names, then clear the cache and repeat the verification.
Adopting Site Handling gives you a single, version‑controlled source of truth for multi‑site and multi‑language behaviour, reduces reliance on TypoScript conditions, and makes environment promotion predictable.