Configuring TYPO3 Site Handling for Multi‑Language Domains

The problem: missing language fallback leads to 404s

You run a TYPO3 site that serves multiple domains (e.g., example.com and example.de). Editors added a new language — French — but visitors who request a page that has no French translation see a 404 instead of falling back to German. The site’s TypoScript constants still work for the default language, but the new language isn’t routed correctly.

Why TYPO3 Site Handling solves this

Starting with TYPO3 9 LTS, site configuration lives in YAML files under config/sites/<site‑identifier>/config.yaml. This file defines:

• Entry points (base URLs, protocols, ports)
• Language configurations, including fallbackType and fallbackLanguage
• Error handling and route enhancers for speaking URLs

When a request arrives, TYPO3 matches the host against the baseVariants, picks the site, then selects the language based on the sys_language_uid in the URL or the Accept‑Language header. If the requested language has no translation, the fallback chain you define is used automatically.

Worked example: add French with German fallback

Assume your site identifier is my_site and the existing YAML looks like this:

# config/sites/my_site/config.yaml
rootPageId: 1
base:
  - /
  languages:
    - title: English
      languageId: '0'
      locale: en_US.UTF-8
      iso-639-1: en
      navigationTitle: English
      hreflang: en-US
      direction: ltr
      flag: us
      fallbackType: strict
      fallbacks: ''
    - title: Deutsch
      languageId: '1'
      locale: de_DE.UTF-8
      iso-639-1: de
      navigationTitle: Deutsch
      hreflang: de-DE
      direction: ltr
      flag: de
      fallbackType: strict
      fallbacks: ''
env:
  - '
'

To add French (fr) that falls back to German when no translation exists:

1. Open config/sites/my_site/config.yaml in your editor.
2. Append a new language block after the existing ones:

    - title: Français
      languageId: '2'
      locale: fr_FR.UTF-8
      iso-639-1: fr
      navigationTitle: Français
      hreflang: fr-FR
      direction: ltr
      flag: fr
      fallbackType: fallback
      fallbacks: '1'   # languageId of German

Key points:

• fallbackType: fallback tells TYPO3 to use the fallbacks list when a page isn’t translated.
• The value '1' matches the languageId of German; you can chain multiple IDs if needed.

Save the file.

Verification and cache flush

Editing the YAML does not take effect immediately because the routing is compiled into a cache.

1. In the TYPO3 backend, go to Site Management and confirm that the site my_site now lists three languages.
2. Clear the system cache: either via the Install Tool → “Flush all caches” or the backend module Maintenance → Flush caches.
3. Open a page that has no French translation, e.g., https://example.com/about-us and add the language parameter ?L=2 or set the Accept‑Language header to fr.
4. Verify that the page renders in German (the fallback) and that the html lang attribute is de.

If you still see a 404, double‑check that the languageId you used in fallbacks matches an existing language block and that the cache was cleared.

Trade‑off: cache clearing can cause a brief stale‑routing window

Because the site configuration is cached, any change to config.yaml is invisible to visitors until the system cache is flushed. On a high‑traffic site, flushing the cache can temporarily increase load as pages are regenerated. To minimise impact:

• Perform the change during a low‑traffic window.
• Use the Flush only site caches option if available (it clears only the routing cache, not all caches).
• Monitor the backend logs for any routing warnings after the flush.

Actionable closing: rollback if needed

If the new language causes unexpected behaviour, you can revert:

1. Remove the French language block from config/sites/my_site/config.yaml.
2. Save the file.
3. Flush the system cache again.
4. Confirm in Site Management that only the original languages remain.

After verifying the rollback, test a few pages to ensure the fallback chain works as before.

By managing languages directly in Site Handling YAML, you keep domain and language routing declarative, version‑friendly, and independent of TypoScript constants—making multi‑domain, multi‑language TYPO3 projects easier to maintain.