Contao Multilingual Pagetree

Mehrsprachige Contao-Websites in einem gemeinsamen Seitenbaum verwalten — ohne für jede Sprache einen eigenen Seitenbaum anzulegen.

Überblick

Das Problem: ein Seitenbaum je Sprache

Wer eine Contao-Website zweisprachig aufsetzt, legt üblicherweise einen zweiten Website-Startpunkt an — und damit einen zweiten, vollständigen Seitenbaum. Bei drei Sprachen sind es drei Bäume, bei fünf Sprachen fünf. Die Struktur ist dann nicht einmal vorhanden, sondern so oft, wie es Sprachen gibt.

Im redaktionellen Alltag kostet das an denselben Stellen immer wieder Zeit:

• Jede neue Seite entsteht mehrfach. Eine Seite anzulegen heißt, sie in jedem Sprachbaum anzulegen — an der richtigen Stelle, mit der richtigen Sortierung, mit denselben Einstellungen.
• Strukturänderungen müssen wiederholt werden. Eine Seite verschieben, umbenennen, schützen oder ein Layout zuweisen: einmal je Baum. Wird einer vergessen, laufen die Sprachen auseinander.
• Die Bäume driften auseinander. Nach einigen Monaten hat die eine Sprache Seiten, die die andere nicht hat — und niemand sieht auf einen Blick, welche.
• Nichts zeigt den Übersetzungsstand. Ob eine Seite übersetzt ist, ob die Übersetzung noch zum aktuellen Ausgangstext passt oder ob sie nach einer Textänderung veraltet ist, steht nirgends.
• Redakteure wechseln ständig den Kontext. Wer einen Text in drei Sprachen pflegt, öffnet drei Seitenbäume, sucht dreimal dieselbe Seite und vergleicht von Hand.

Für Websites, deren Sprachen inhaltlich dasselbe sagen sollen, ist die vervielfachte Struktur reiner Verwaltungsaufwand: Dieselbe Information wird mehrfach gepflegt, obwohl sich nur der Text unterscheidet.

Die Lösung: ein Baum, Sprachregister im Formular

Das Grundprinzip in einem Satz: Jeder Contao-Website-Startpunkt besitzt genau eine Ausgangssprache und beliebig viele zusätzlich konfigurierte Zielsprachen, die sich denselben Seitenbaum teilen; Übersetzungen entstehen über Sprachregister direkt in den gewohnten Contao-Bearbeitungsformularen.

Die Struktur existiert damit genau einmal. Eine Seite wird einmal angelegt, einmal einsortiert und einmal konfiguriert — und ist anschließend in jeder konfigurierten Sprache vorhanden. Übersetzt wird nicht in einem getrennten Baum, sondern im selben Bearbeitungsformular, über Register oberhalb der Felder.

Aufgabe	Getrennte Seitenbäume	Mit diesem Paket
Seite anlegen	einmal je Sprache	einmal insgesamt
Seite verschieben oder umbenennen	einmal je Sprache	einmal insgesamt
Text übersetzen	anderen Baum öffnen, Seite suchen	Sprachregister im selben Formular
Übersetzungsstand erkennen	manuell vergleichen	Prüfstatus je Übersetzung
Unübersetzte Seite im Frontend	fehlt oder ist leer	je Sprache einstellbar: ausblenden oder Standardseite zeigen

Konkret adressiert das Paket die oben genannten Punkte so:

• Gemeinsame Struktur. Alle Sprachen eines Startpunkts teilen sich eine Seitenstruktur; Typ, Position, Reihenfolge und Beziehungen bleiben mit der Ausgangssprache verbunden.
• Übersetzen im gewohnten Formular. Sprachregister erscheinen in den nativen Contao-Masken für Seiten, Artikel, Inhaltselemente, Nachrichten, Termine und FAQ.
• Feldweise Entscheidung. Je Feld ist wählbar, ob es den Ausgangswert erbt, eine eigene Übersetzung trägt oder bewusst leer bleibt — geerbte Felder folgen späteren Änderungen der Ausgangssprache automatisch.
• Sichtbarer Übersetzungsstand. Ein redaktioneller Prüfstatus meldet, wenn sich die Ausgangssprache seit der letzten Prüfung geändert hat.
• Kontrolliertes Verhalten bei Lücken. Je Sprache ist einstellbar, ob eine nicht übersetzte Seite unerreichbar ist oder die Standardseite zeigt — und getrennt davon, ob nicht übersetzte Inhalte ausgelassen oder aus der Quelle ausgegeben werden.
• Freie Sprachen, wo nötig. Soll eine Sprache redaktionell eigenständig arbeiten, erhält sie eine eigene Artikel- und Inhaltsstruktur — einstellbar je Sprache und jederzeit änderbar, ohne Daten zu verlieren.
• URLs je Sprache. Protokoll, eigene Domain und Einstiegspfad sind je Sprache konfigurierbar: gleiche Domain mit Pfadpräfixen, getrennte Domains oder eine Mischung.

Wann dieses Paket passt

Situation	Einschätzung
Die Sprachen sollen dieselbe Struktur und dieselben Inhalte zeigen, nur in anderer Sprache	Der Kernfall. Verbundener Modus.
Die meisten Sprachen sind Übersetzungen, eine einzelne soll eigene Inhalte führen	Möglich: Modus je Sprache getrennt einstellbar.
Jede Sprache ist inhaltlich eine eigene Website mit eigener Navigation	Der geteilte Baum bringt dann wenig; getrennte Startpunkte bleiben sinnvoll.
Mehrere Websites in einer Contao-Installation	Unterstützt: Jeder Website-Startpunkt bildet eine eigene Website-Grenze. Sprachen, Lizenz und Übersetzungsdaten werden je Startpunkt getrennt verwaltet und sind gegeneinander isoliert.

Eigenschaft	Wert
Paket	vtinnovations/contao-multilingual-pagetree
Typ	contao-bundle
Namensraum	Vtinnovations\ContaoMultilingualPagetree
Lizenz	proprietär — kostenlos, lebenslang, je Website-Startpunkt zu aktivieren

Teil 1 — Einrichtung

Von der Installation bis zur ersten übersetzten Seite sind es sechs Etappen:

1. Vorbereiten — sichern, Voraussetzungen prüfen, Sprachen festlegen
2. Paket installieren — über den Contao Manager oder mit Composer
3. Installation überprüfen
4. Lizenz aktivieren — je Website-Startpunkt
5. Zielsprachen anlegen und veröffentlichen
6. Erste Übersetzung erstellen und den Sprachwechsler einbinden

Voraussetzungen

Anforderung	Version
PHP	^8.1
Contao	^5.0 (contao/core-bundle)
Composer	für Installation und Aktualisierung
PHPUnit	^10.5 (nur Entwicklung)

Die Integrationen für News, Kalender und FAQ werden nur aktiv, wenn das jeweilige Contao-Bundle installiert ist. Contao 4 wird nicht unterstützt.

Vor der Installation

1. Sichern Sie die Datenbank und das Verzeichnis files/.
2. Prüfen Sie die Systemvoraussetzungen.
3. Halten Sie fest, welche Sprachen jeder Website-Startpunkt ausliefern soll.
4. Halten Sie fest, welche Sprache je Startpunkt die Ausgangssprache ist. Maßgeblich ist die native Contao-Sprache des Startpunkts.
5. Installieren und prüfen Sie zuerst auf einer Testumgebung mit einer Kopie der Produktivdaten.

Das Paket schreibt ausschließlich unterhalb von var/, also außerhalb des öffentlichen Verzeichnisses. Der PHP-Prozess benötigt dort Schreibrechte:

Verzeichnis	Zweck
var/contao-multilingual-pagetree/state/	interner Betriebszustand
var/contao-multilingual-pagetree/licences/	gespeicherter Lizenzstatus je Website-Startpunkt

Beide Verzeichnisse müssen für den PHP-Prozess beschreibbar sein. Ein noch nicht vorhandenes Verzeichnis ist ein gültiger Ausgangszustand.

Installation über den Contao Manager

Contao Multilingual Pagetree ist ein proprietäres Paket, das auf Packagist veröffentlicht ist. Die Installation erfolgt daher auf dem üblichen Weg. Ein zusätzlicher Repository-Eintrag oder ein manuell bereitgestelltes Archiv sind nicht erforderlich.

1. Öffnen Sie den Contao Manager und melden Sie sich an.
2. Wechseln Sie in den Bereich Pakete.
3. Suchen Sie nach vtinnovations/contao-multilingual-pagetree und fügen Sie das Paket hinzu.
4. Führen Sie die Paketänderungen aus. Der Contao Manager installiert das Paket und aktualisiert den Autoloader.
5. Wechseln Sie anschließend in den Bereich Wartung und führen Sie die Datenbankmigration aus.
6. Leeren Sie den Anwendungscache.

Installation über Composer

Alternativ auf der Kommandozeile:

composer require vtinnovations/contao-multilingual-pagetree

Anschließend Contao einrichten und die Datenbank aktualisieren:

vendor/bin/contao-console cache:clear
vendor/bin/contao-console contao:migrate

In einer Contao Managed Edition fasst der folgende Befehl das Einrichten der Anwendung einschließlich der Veröffentlichung der Bundle-Assets zusammen:

vendor/bin/contao-console contao:setup

Bestehende Installation aktualisieren

composer update vtinnovations/contao-multilingual-pagetree
vendor/bin/contao-console contao:migrate
vendor/bin/contao-console cache:clear

Im Contao Manager entspricht das dem Aktualisieren des Pakets, gefolgt von Datenbankmigration und Cache-Neuaufbau.

Installation überprüfen

Lassen Sie die Konsolenbefehle des Pakets auflisten:

vendor/bin/contao-console list contao-multilingual-pagetree

Erscheinen die Befehle des Pakets, ist das Bundle registriert und der Dienstcontainer wurde erfolgreich übersetzt. Im Backend erscheint zusätzlich an jedem Website-Startpunkt in der Seitenstruktur die Aktion Zusätzliche Sprachen verwalten (Globus-Symbol).

Lizenz aktivieren

Domain prüfen und Lizenz aktivieren.

1. Stellen Sie sicher, dass am Contao-Website-Startpunkt die korrekte primäre Domain eingetragen ist.
2. Öffnen Sie Seitenstruktur und bearbeiten Sie den Website-Startpunkt.
3. Geben Sie den Lizenzschlüssel im Abschnitt Contao Multilingual Pagetree Licence management in das Feld Lizenzschlüssel ein.
4. Wählen Sie Lizenz aktivieren.
5. Nach erfolgreicher Aktivierung werden Lizenzstatus, Lizenzdomain, Lizenzlaufzeit und Aktivierungsstatus aktualisiert angezeigt.

Im Lizenzbereich stehen diese Aktionen zur Verfügung:

Aktion	Wirkung
Lizenz aktivieren	erstmalige Aktivierung dieses Website-Startpunkts
Lizenz ersetzen	einen vorhandenen Schlüssel durch einen anderen ersetzen
Lizenz aktualisieren	den Lizenzstatus bewusst neu abrufen
Lizenz prüfen	den bereits gespeicherten Status lokal erneut prüfen, ohne ihn neu abzurufen
Lizenz entfernen	gespeicherten Lizenzstatus dieses Startpunkts entfernen; Inhalte und Übersetzungen bleiben bestehen

Zielsprachen anlegen

Sprachverwaltung öffnen. Speichern Sie den Startpunkt und öffnen Sie in der Seitenstruktur die Aktion Zusätzliche Sprachen verwalten (Globus-Symbol) in der Zeile des Website-Startpunkts. Die Aktion erscheint nur an Seiten vom Typ Website-Startpunkt und nur, wenn Sie diesen Startpunkt verwalten dürfen.

Sprachen hinzufügen. Über Sprache hinzufügen legen Sie je Zielsprache einen Datensatz an. Die native Contao-Sprache des Startpunkts ist die Standard-/Ausgangssprache und wird hier nicht erneut angelegt.

Das Formular ist in vier Abschnitte gegliedert:

Abschnitt	Felder
Spracheinstellungen	Sprache, Sprachbezeichnung, Flagge
Sprach-URL	Protokoll, Domain, Einstiegspfad
Seitenverfügbarkeit	Seitenverfügbarkeit, Inhaltsübersetzungsmodus, Inhaltsstrukturmodus
Veröffentlichung	Veröffentlichen

Beim Feld Sprache wird der zugehörige Sprachcode automatisch gespeichert, die Sprachbezeichnung automatisch vorbelegt und eine Standard-Flagge automatisch ausgewählt, die Sie ändern können. Mitgelieferte Flaggen: at, br, de, en, es, fr, gb, it, ja, jp, nl, pl, pt, ru, us, zh.

Sprache veröffentlichen. Erst die Option Veröffentlichen („Diese Sprache im Frontend verfügbar machen.“) macht die Sprache im Frontend verfügbar. Die Sichtbarkeit lässt sich in der Liste auch direkt über Sichtbarkeit umschalten ändern.

Erste Übersetzung

Datensatz übersetzen. Öffnen Sie eine Seite, einen Artikel, eine Nachricht, einen Termin oder eine FAQ im gewohnten Bearbeitungsformular. Oberhalb des Formulars erscheinen Sprachregister. Wechseln Sie auf das Register der Zielsprache und füllen Sie die übersetzbaren Felder aus.

Für Seiten sind das Seitenname, Seitenalias, Seitentitel und Beschreibung der Seite. Jedes übersetzbare Feld erhält zusätzlich das Auswahlfeld Übersetzungsstatus — siehe Übersetzungsstatus je Feld.

Inhaltselemente werden anders bearbeitet: dort gibt es keine zusätzlichen Auswahlfelder. Siehe Inhaltselemente übersetzen.

Sprachwechsler einbinden

Modul anlegen und einfügen. Legen Sie unter Layout → Module ein Modul vom Typ Contao Multilingual Pagetree Sprachwechsler (Kategorie Verschiedenes) an, wählen Sie Darstellung des Sprachumschalters und Nicht verfügbare Sprachen, und binden Sie das Modul im Seitenlayout oder als Inhaltselement ein.

Damit ist die Einrichtung abgeschlossen: Der Startpunkt ist lizenziert, die Zielsprachen sind angelegt und veröffentlicht, ein erster Datensatz ist übersetzt und Besucher können die Sprache wechseln.

Teil 2 — Funktionen im Detail

Spracheinstellungen

Jeder Sprachdatensatz eines Startpunkts kennt diese Felder:

Feld	Hilfetext im Backend
Sprache	Wählen Sie die Sprache. Der zugehörige Sprachcode wird automatisch gespeichert.
Sprachbezeichnung	Bitte geben Sie die Sprachbezeichnung ein (z. B. English, Deutsch).
Flagge	Wählen Sie die Flagge für diese Sprache. Eine Standardflagge wird automatisch ausgewählt und kann geändert werden.
Veröffentlichen	Diese Sprache im Frontend verfügbar machen.
Historische Ausgangsmarkierung	Nur zur Kompatibilität. Maßgeblich ist die native Contao-Sprache des Startpunkts.

In der Seitenstruktur zeigt der Website-Startpunkt zusätzlich Sprachkürzel als Badges; an einzelnen Seiten erscheint ein Badge für die Standardsprache und je ein Badge für vorhandene Übersetzungen in den unter diesem Startpunkt veröffentlichten Sprachen. Nicht veröffentlichte Übersetzungen werden dabei mit (Off) gekennzeichnet.

Sprach-URL: Protokoll, Domain und Einstiegspfad

Jede Sprache kann im Abschnitt Sprach-URL eine eigene Adresse erhalten. Alle drei Felder sind optional; solange sie leer sind, behält der Datensatz exakt das URL-Verhalten, das er ohne diese Felder hätte.

Protokoll

• Von der Website-Wurzel übernehmen (Standard) — die Sprache verwendet das Protokoll des Startpunkts.
• HTTPS oder HTTP — die Sprache verwendet fest dieses Protokoll.

Das Protokoll allein unterscheidet niemals zwei Sprachen: Zwei Sprachen mit demselben Hostnamen und demselben Einstiegspfad dürfen sich nicht nur im Protokoll unterscheiden.

Domain

Hilfetext: „Optional. Leer lassen, um die Domain der Website-Wurzel zu verwenden. Geben Sie nur einen Hostnamen ein, z. B. www.example.de.“

Der Hostname wird exakt übernommen: Groß-/Kleinschreibung und ein versehentlicher Schlusspunkt werden bereinigt, sonst nichts. example.com und www.example.com bleiben zwei verschiedene Adressen; ein www wird weder ergänzt noch entfernt. Protokolle, Pfade, Query-Strings, Fragmente, Ports und Platzhalter werden abgewiesen.

Einstiegspfad

Hilfetext: „Optionaler Sprachpfad, z. B. /de. Verwenden Sie / für das Domain-Stammverzeichnis.“

Was ein leeres Feld bedeutet, hängt davon ab, ob die Sprache eine eigene Domain hat:

• mit eigener Domain: Die Sprache liegt im Stammverzeichnis dieser Domain; der Sprachcode wird nicht angehängt.
• ohne eigene Domain: Die bisherige Adressbildung bleibt erhalten — Standardsprache ohne Präfix, jede andere Sprache unter ihrem Sprachcode.

Bequeme Eingaben werden normalisiert: de wird zu /de, /de/ wird zu /de. Ein Einstiegspfad greift immer auf vollständigen Pfadsegmenten: /de gilt für /de, /de/ und /de/ueber-uns, aber niemals für /demo oder /development.

Beispiele

Gleiche Domain mit Einstiegspfaden:

Sprache	Domain	Einstiegspfad	Adresse
Englisch	(leer)	/	https://www.xyz.com/
Deutsch	(leer)	/de	https://www.xyz.com/de
Russisch	(leer)	/ru	https://www.xyz.com/ru

Getrennte Domains:

Sprache	Domain	Einstiegspfad	Adresse
Englisch	(leer)	/	https://www.xyz.com/
Deutsch	www.xyz.de	/	https://www.xyz.de/
Russisch	www.xyz.ru	/	https://www.xyz.ru/

Gemischt:

Sprache	Domain	Einstiegspfad	Adresse
Englisch	(leer)	/	https://www.xyz.com/
Deutsch	www.xyz.de	/de	https://www.xyz.de/de
Russisch	(leer)	/ru	https://www.xyz.com/ru

Was beim Speichern abgewiesen wird

Damit eine eingehende Anfrage eindeutig auflösbar bleibt, lehnt die zentrale Kollisionsprüfung diese Konstellationen mit einer Meldung ab, statt sie aufzulösen:

Situation	Meldung im Backend
Zwei Sprachen mit gleicher Domain und gleichem Einstiegspfad	Eine andere Sprache dieser Website-Wurzel verwendet bereits diese Domain und diesen Einstiegspfad.
Mehrere Sprachen beanspruchen / auf demselben Hostnamen	Eine andere Sprache dieser Website-Wurzel verwendet bereits das Domain-Stammverzeichnis dieses Hostnamens.
Unterscheidung allein über das Protokoll	Zwei Sprachen dürfen sich bei gleichem Hostnamen und gleichem Einstiegspfad nicht nur im Protokoll unterscheiden.
Hostname gehört bereits zu einer anderen Website-Wurzel	Dieser Hostname gehört bereits zu einer anderen Website-Wurzel; eingehende Anfragen wären dadurch nicht eindeutig auflösbar.
Einstiegspfad nicht eindeutig auflösbar	Dieser Einstiegspfad ist gegenüber den anderen Sprachen dieser Website-Wurzel nicht eindeutig auflösbar.
Protokoll im Domain-Feld	Bitte geben Sie nur einen Hostnamen ohne Protokoll ein, z. B. www.example.de.
Vollständige URL im Einstiegspfad	Bitte geben Sie nur einen Pfad ein, keine vollständige URL.
. oder .. im Einstiegspfad	Der Einstiegspfad darf keine Segmente "." oder ".." enthalten.

Zwei Sprachen dürfen / nur dann gleichzeitig verwenden, wenn sich ihre Hostnamen unterscheiden.

Seitenverfügbarkeit

Das Feld Seitenverfügbarkeit („Legt fest, wie Seiten ohne Übersetzung in dieser Sprache behandelt werden.“) gilt je Zielsprache. Die Standardsprache verwendet immer den Quellseitenbaum; für sie wird der Abschnitt ausgeblendet.

Option	Verhalten
Seiten ohne Übersetzung ausblenden	Seiten ohne verfügbare Übersetzung sind in dieser Sprache nicht erreichbar.
Standardseite anzeigen	Seiten ohne verfügbare Übersetzung verwenden den aktuellen Seiteninhalt der Standardsprache und behalten dabei die angeforderte Sprach-URL und Oberflächensprache.

Der Standardwert eines neuen Sprachdatensatzes ist Standardseite anzeigen.

Inhaltsstrukturmodus

Der Inhaltsstrukturmodus bestimmt, ob die Zielsprache der Struktur der Ausgangssprache folgt oder eine eigene besitzt.

Option	Verhalten
Verbundene Übersetzung	Die übersetzte Sprache folgt der Artikel- und Inhaltselementstruktur der Quelle. Redakteure übersetzen Felder, während Typ, Position, Reihenfolge und Beziehungen mit der Quelle verbunden bleiben.
Freier Sprachinhalt	Die übersetzte Sprache hat eine eigenständige Artikel- und Inhaltsstruktur und kann vollständig von der Ausgangssprache abweichen.

Der Standardwert eines neuen Sprachdatensatzes ist Verbundene Übersetzung.

Inhaltsübersetzungsmodus

Getrennt von der Seitenverfügbarkeit legt der Inhaltsübersetzungsmodus fest, „wie nicht übersetzte Inhalte in dieser Sprache dargestellt werden“:

Option	Verhalten
Standardinhalt anzeigen, wenn keine Übersetzung vorhanden ist	Nicht übersetzte Inhalte werden aus der Ausgangssprache ausgegeben, ohne sie zu kopieren.
Inhalte ohne Übersetzung nicht anzeigen	Nicht übersetzte Inhaltselemente werden ausgelassen.

Wenn Sie ein Feld bewusst leeren und speichern, bleibt es in dieser Sprache leer — auch bei aktivem Rückfall.

Übersetzbare Felder

Das Paket arbeitet nach dem Prinzip default deny: Übersetzbar ist ausschließlich, was ausdrücklich registriert ist. Der Kernbestand:

Datensatztyp	Übersetzbare Felder
Seite	title, pageTitle, description, alias
Artikel	title
Nachricht	headline, subheadline, teaser, text, alias, pageTitle, description
Termin	title, teaser, details, location, alias, pageTitle, description
FAQ	question, answer, alias

Bei Inhaltselementen hängt der Umfang vom Elementtyp ab. headline ist bei jedem Typ übersetzbar; darüber hinaus gilt:

Elementtyp	Zusätzlich übersetzbare Felder
text	text, alt, imageTitle, caption
accordionSingle	text
headline	—
html	html
code	code
list	listitems
table	tableitems, summary
hyperlink	linkTitle
image	alt, imageTitle, caption
gallery	caption
player	playerCaption
download	linkTitle
downloads	linkTitle

Strukturelle Felder (unter anderem type, CType, colPos, sorting, singleSRC, size, customTpl, cssID, protected, groups) sowie technische Felder können niemals als übersetzbar deklariert werden. Die Felder published, start, stop und invisible sind je Sprache unabhängig statt übersetzt — sie können also pro Sprache eigenständig gesetzt werden.

Übersetzungsstatus je Feld

Bei Seiten, Artikeln, Nachrichten, Terminen und FAQ erhält jedes übersetzbare Feld ein Auswahlfeld Übersetzungsstatus mit dem Hilfetext „Geerbte Felder übernehmen zukünftige Änderungen der Ausgangssprache automatisch.“

Auswahl	Wirkung
Aus Ausgangssprache übernehmen	Der aktuelle Quellwert wird verwendet und folgt späteren Änderungen der Ausgangssprache.
Eigene Übersetzung verwenden	Der eingegebene Sprachwert wird verwendet.
Bewusst leer lassen	Das Feld bleibt in dieser Sprache leer.

Zur Orientierung zeigt das Formular zusätzlich den Aktuellen Ausgangswert an.

Inhaltselemente übersetzen

Inhaltselemente werden bewusst anders bedient als die übrigen Datensätze. Wählen Sie die Sprache über die Sprachregister oben im Formular. Das Formular einer Zielsprache ist dasselbe Formular wie in der Ausgangssprache: dieselben Abschnitte, dieselbe Feldreihenfolge, derselbe Editor und dieselben Auswahlfelder. Sie übersetzen direkt in den gewohnten Feldern.

Es gibt hier keine zusätzlichen Auswahlfelder pro Feld und keinen gesonderten Abschnitt für übersetzbare Inhalte. Das aktive Sprachregister zeigt bereits, welche Sprache Sie bearbeiten.

Felder, die zur Struktur des Elements gehören — etwa Elementtyp, Bildauswahl, Bildgröße oder CSS-Angaben — werden im verbundenen Modus von der Ausgangssprache bestimmt und sind deshalb nicht bearbeitbar. Ein Textelement bleibt daher in jeder Sprache ein Textelement und zeigt dasselbe Formular. Im freien Modus wählen Sie den Elementtyp wie gewohnt selbst.

Schlägt das Speichern fehl, meldet das Backend: „Die Übersetzung konnte nicht gespeichert werden. Die Ausgangssprache wurde nicht verändert.“

Prüfstatus nach Quelländerungen

Der Prüfstatus („Redaktioneller Prüfstatus dieser Übersetzung.“) zeigt, ob eine Übersetzung nach einer Änderung der Ausgangssprache erneut zu prüfen ist.

Status	Bedeutung
Noch nicht geprüft	Für diese Übersetzung wurde noch kein Prüfstand gespeichert.
Aktuell	Der geprüfte Stand entspricht dem aktuellen Quellstand.
Prüfung erforderlich	Die Ausgangssprache hat sich seit der letzten Prüfung geändert.
Quelldatensatz nicht verfügbar	Der verbundene Quelldatensatz ist nicht verfügbar, daher kann diese Übersetzung nicht geprüft werden.

Die Aktion Übersetzung als geprüft markieren („Den aktuellen Stand der Quelle als geprüft speichern.“) speichert den redaktionellen Stand und meldet anschließend „Die Übersetzung wurde als geprüft markiert.“ Sie ändert weder Veröffentlichung noch Routing. Das Panel zeigt außerdem Geprüft am, Geprüft von, Geänderte Quellfelder, Geprüfter Quellwert und Aktueller Quellwert.

Der Prüf-Workflow gilt für Seiten, Artikel, Nachrichten, Termine und FAQ. Inhaltselemente sind bewusst ausgenommen: Ein Inhaltselement wird als Teil der Seite geprüft, auf der es liegt, und trägt deshalb keinen eigenen Prüfstatus — kein Statusfeld, kein Panel und keine Prüfaktion auf den Sprachregistern.

Sprachwechsler-Modul

Das Frontend-Modul Contao Multilingual Pagetree Sprachwechsler („Zeigt einen Sprachwechsler für verbundene Übersetzungen an.“) hat den Typ language_switcher und liegt in der Kategorie Verschiedenes.

Darstellung des Sprachumschalters („Bitte wählen Sie den Anzeigestil für den Sprachwechsler.“) bietet sechs Optionen:

Option	Wert
Flaggen horizontal (Standard)	horizontal_flags
Beschriftungen horizontal	horizontal_labels
Flaggen mit Beschriftungen horizontal	horizontal_flags_labels
Flaggen vertikal	vertical_flags
Beschriftungen vertikal	vertical_labels
Flaggen mit Beschriftungen vertikal	vertical_flags_labels

Nicht verfügbare Sprachen („Legt fest, wie Sprachen dargestellt werden, in denen die aktuelle Seite oder der aktuelle Detaildatensatz nicht verfügbar ist.“) kennt zwei Werte: Nicht verfügbare Sprachen ausblenden (Standard) und Nicht verfügbare Sprachen deaktiviert anzeigen. Im zweiten Fall lautet der Hinweistext „In dieser Sprache nicht verfügbar“.

Aktive Sprache ausblenden („Die aktuell aktive Sprache nicht in der Liste anzeigen.“) entfernt den Eintrag der laufenden Sprache. Das Modulformular bietet zusätzlich die üblichen Abschnitte für ein eigenes Template (customTpl), Zugriffsschutz und cssID.

Ausgeliefert werden die Templates mod_language_switcher.html.twig und mod_language_switcher.html5.

Kanonische URLs und hreflang

Kanonische Adressen, hreflang und x-default werden automatisch ausgegeben und verwenden jeweils Protokoll, Hostnamen und Einstiegspfad der Zielsprache. Dasselbe gilt für den Sprachwechsler und die Detailumschaltung für Nachrichten, Termine und FAQ.

Berechtigungen

Der Zugriff folgt den nativen Contao-Mechanismen: Administratoren haben immer Zugriff; andere Backend-Benutzer benötigen das Modul Seitenstruktur, die passende Seitenfreigabe sowie die normalen Tabellen- und Feldrechte. Eine eigene paketbezogene Lizenzberechtigung gibt es nicht.

Alle schreibenden Vorgänge werden serverseitig geprüft. Eine im Formular ausgeblendete Schaltfläche gilt nicht als Berechtigung; schreibende Backend-Aktionen laufen über POST mit Contao-Anfrage-Token. Wird eine Aktion als Link statt als Formular aufgerufen, meldet das Backend: „Diese Aktion muss abgesendet und darf nicht als Link geöffnet werden.“

Fällt das Backend auf die Ausgangssprache zurück, nennt es die Kategorie des Grundes:

Situation	Meldung
Sprache nicht konfiguriert	Diese Sprache ist für diese Website-Wurzel nicht konfiguriert.
Sprache nicht veröffentlicht	Diese Sprache ist für diese Website-Wurzel nicht veröffentlicht und kann daher nicht bearbeitet werden.
Sprache eines anderen Startpunkts	Diese Sprache gehört zu einer anderen Website-Wurzel und kann hier nicht bearbeitet werden.
Fehlende Berechtigung	Sie dürfen die Sprachen dieser Website-Wurzel nicht bearbeiten.
Keine gültige Lizenz	Für die Bearbeitung von Übersetzungen ist eine gültige Lizenz erforderlich.
Domain des Startpunkts fehlt	Konfigurieren Sie die Domain dieser Website-Wurzel, bevor Sie Übersetzungen bearbeiten.

Ohne Lizenz gilt für den Funktionsumfang:

Funktion	Ohne Lizenz	Mit Lizenz
Zusätzliche Sprachen anlegen und bearbeiten	Nicht verfügbar	Verfügbar
Übersetzungen bearbeiten	Nicht verfügbar	Verfügbar
Redaktioneller Prüfstatus	Nicht verfügbar	Verfügbar
Freier Inhaltsmodus	Nicht verfügbar	Verfügbar
Integritätsreparatur	Nicht verfügbar	Verfügbar
Frontend-Ausgabe bestehender Übersetzungen	Verfügbar	Verfügbar

Teil 3 — Für Entwickler

Konsolenbefehle

Das Paket registriert vier Befehle:

vendor/bin/contao-console contao-multilingual-pagetree:integrity:scan
vendor/bin/contao-console contao-multilingual-pagetree:integrity:repair
vendor/bin/contao-console contao-multilingual-pagetree:data-report
vendor/bin/contao-console contao-multilingual-pagetree:registration

integrity:scan

„Scans multilingual records for integrity issues (read-only).“ Der Scan verändert keine Daten.

Option	Bedeutung
--root	Limit the scan to one root page id
--language	Limit the scan to one language code
--entity	Limit the scan to one entity type
--severity	Only report this severity or higher (Standard: info)
--format	Output format: text or json (Standard: text)

Gemeldete Schweregrade sind Information, Warnung, Fehler und Kritisch. Zur Reparaturfähigkeit unterscheidet der Bericht Keine Reparatur verfügbar, Wird automatisch repariert, Reparatur erfordert Bestätigung und Manuelle Entscheidung erforderlich.

Alle Befundarten des Integritätsscans

Code	Bezeichnung
invalid_language_configuration	Ungültige Sprachkonfiguration
duplicate_language_configuration	Doppelte Sprachkonfiguration
multiple_fallback_languages	Mehrere Standardsprachen
missing_fallback_language	Keine Standardsprache konfiguriert
invalid_root_relation	Ungültige Startseiten-Beziehung
missing_source	Fehlender Quelldatensatz
self_referential_source	Übersetzung verweist auf sich selbst
translation_source_relation	Übersetzung verweist auf eine andere Übersetzung
cross_site_relation	Beziehung überschreitet eine Website-Grenze
cross_language_relation	Beziehung überschreitet eine Sprachgrenze
duplicate_translation	Doppelte Übersetzung
orphaned_connected_translation	Verwaiste verbundene Übersetzung
orphaned_free_content	Verwaister freier Inhalt
invalid_free_parent	Ungültiges übergeordnetes Element für freien Inhalt
free_content_cycle	Zyklische Beziehung im freien Inhalt
invalid_field_states	Ungültiger Feldstatus
invalid_review_metadata	Ungültige Prüf-Metadaten
invalid_alias	Ungültiger Alias
duplicate_alias	Doppelter Alias
invalid_publication_range	Ungültiger Veröffentlichungszeitraum
inactive_connected_data	Inaktive verbundene Daten (erhalten)
inactive_free_data	Inaktiver freier Inhalt (erhalten)
rule_failure	Eine Integritätsregel ist fehlgeschlagen

integrity:repair

„Repairs multilingual integrity issues (dry run by default).“

Option	Bedeutung
--root	Limit the repair to one root page id
--language	Limit the repair to one language code
--entity	Limit the repair to one entity type
--execute	Actually apply the repair plan
--force	Also apply destructive actions
--format	Output format: text or json (Standard: text)

data-report

„Reports the multilingual data this bundle stores (read-only).“ Einzige Option: --format („Output format: text or json“, Standard text).

registration

„Activates, refreshes or reports the product registration of this installation.“ Das Argument action ist optional und akzeptiert status (Standard), activate, refresh und remove.

Option	Bedeutung
--key	Subscription key, required for "activate"
--force	Confirms "remove"
--root	Required Contao root page ID

--root ist Pflicht: Ohne gültige Wurzelseiten-ID bricht der Befehl mit „A valid root page is required: --root=<id>.“ ab; hat die gewählte Wurzelseite keine gültige Domain, meldet er „The selected root page has no valid configured domain.“ Der Schlüssel wird nie ausgegeben, protokolliert oder zurückgeschrieben.

Tabellen und Verzeichnisse

Tabelle	Zweck
tl_inline_language	Sprachkonfiguration je Website-Startpunkt (ptable: tl_page)
tl_page_translation	Seitenübersetzungen
tl_article_translation	Artikelübersetzungen
tl_content_translation	Inhaltselementübersetzungen — reine Ablage
tl_news_translation	Nachrichtenübersetzungen
tl_calendar_events_translation	Terminübersetzungen
tl_faq_translation	FAQ-Übersetzungen
tl_multilingual_pagetree_channel_ledger	interne Ablage; keine Palette, keine Backend-Registrierung

Backend-Zuordnung der Tabellen:

$GLOBALS['BE_MOD']['content']['page']['tables'][]    = 'tl_inline_language';
$GLOBALS['BE_MOD']['content']['page']['tables'][]    = 'tl_page_translation';
$GLOBALS['BE_MOD']['content']['article']['tables'][] = 'tl_article_translation';
// faq, news und calendar nur, wenn das jeweilige Modul vorhanden ist

Routen

Name	Pfad	Methode
contao_multilingual_pagetree_channel_update	/rest/api/v1/contao-multilingual-pagetree-license-updater	—
…_root_licence_activate	/contao-multilingual-pagetree/root/{rootId}/licence/activate	POST
…_root_licence_replace	/contao-multilingual-pagetree/root/{rootId}/licence/replace	POST
…_root_licence_refresh	/contao-multilingual-pagetree/root/{rootId}/licence/refresh	POST
…_root_licence_verify	/contao-multilingual-pagetree/root/{rootId}/licence/verify	POST
…_root_licence_remove	/contao-multilingual-pagetree/root/{rootId}/licence/remove	POST

Die fünf Lizenzrouten laufen im Backend-Scope und akzeptieren nur POST; rootId ist auf \d+ beschränkt. Beim Aktualisierungsendpunkt ist die Methode absichtlich nicht in der Route eingeschränkt: Der Handler beantwortet eine Anfrage, die nicht POST ist, mit einem ausdrücklichen 405 samt Allow-Header, statt den Router daraus einen 404 machen zu lassen.

Hooks und Listener

Hooks werden über das Attribut #[AsHook] registriert, das Frontend-Modul über #[AsFrontendModule]. Cronjobs registriert das Paket keine.

Hook / Event	Listener
getPageLayout, loadPageDetails	PageTranslationListener
getArticle, compileArticle, isVisibleElement	ArticleTranslationListener
getContentElement, isVisibleElement	ContentTranslationListener
parseArticles	NewsTranslationListener
getAllEvents, parseTemplate	CalendarEventsTranslationListener
parseTemplate	FaqTranslationListener
generatePage	LanguageMetadataListener
kernel.request (Priorität 20)	LanguageRequestListener
kernel.finish_request (Priorität −255)	RenderStateResetListener

Erweiterungspunkte

Nur die hier genannten Schnittstellen sind für Fremdcode unterstützt. Alles andere unterhalb von Vtinnovations\ContaoMultilingualPagetree\ ist intern und kann sich in jedem Release ohne Ankündigung ändern, auch in einer Patch-Version. Fremdimplementierungen sind isoliert: Ein Beitrag oder eine Regel, die eine Ausnahme wirft, wird protokolliert und übersprungen, bricht aber nie die Kernrichtlinien oder einen Scan ab.

Übersetzbare Felder registrieren

use Vtinnovations\ContaoMultilingualPagetree\Translation\TranslationFieldPolicyContributorInterface;
use Vtinnovations\ContaoMultilingualPagetree\Translation\TranslationFieldRegistration;

final class ProductNoteTranslationFields implements TranslationFieldPolicyContributorInterface
{
    public function registrations(): iterable
    {
        yield new TranslationFieldRegistration('tl_content', 'note', 'string', 'product_note');
    }
}

Dienste, die das Interface implementieren, werden automatisch getaggt. Vertrag:

• Werttypen: string, headline, serialized_array, boolean, integer, nullable.
• Registrierungen für Inhaltselemente müssen einen Inhaltstyp benennen.
• Strukturelle, technische und veröffentlichungsbezogene Felder können nie umklassifiziert werden; solche Deklarationen werden ignoriert.
• Kernrichtlinien gewinnen immer gegenüber Beiträgen.
• Doppelte Deklarationen werden deterministisch über den Klassennamen aufgelöst; die Registrierungsreihenfolge ändert das Ergebnis nie.
• Registrierte Felder nehmen automatisch an Overlays, Übersetzungsformularen, Prüf-Fingerabdrücken und Integritätsprüfungen teil — weitere Hooks sind nicht nötig.

Eigene Integritätsregeln

use Vtinnovations\ContaoMultilingualPagetree\Integrity\IntegrityRuleInterface;

• scan() muss read-only sein. Schreiben während eines Scans ist eine Vertragsverletzung.
• Die Ausführungsreihenfolge ist deterministisch: absteigende Priorität, dann Regelname.
• getSupportedEntities() mit Rückgabe [] bedeutet „alle Entitäten“.
• Rückgabe ist eine IntegrityIssueCollection; Issue-Codes sollten stabile Zeichenketten sein.
• Nur Befunde mit REPAIR_AUTOMATIC oder REPAIR_CONFIRMATION werden eingeplant; REPAIR_MANUAL wird gemeldet und einer Redakteurin oder einem Redakteur überlassen.
• Ausnahmen werden abgefangen, protokolliert und als rule_failure gemeldet.

Nur lesend nutzbare Dienste

Diese Dienste dürfen konsumiert, aber nicht ersetzt werden. Ihre Methodensignaturen sind stabil, ihre konkreten Klassen nicht Teil des Vertrags.

Dienst	Zweck
Availability\PageAvailabilityResolver	strikte/rückfallende Seitenverfügbarkeit für eine Seite und Sprache
Availability\ResourceAvailabilityResolver	Verfügbarkeit der vollständigen aktuellen Ressource inklusive Detaildatensätzen
Availability\SiteLanguageRegistryInterface	konfigurierte Sprachen, Standardsprache und Modi einer Website-Wurzel
Content\ContentTranslationModeResolver	verbundener oder freier Modus für eine Seite und Sprache
Detail\DetailTargetResolverInterface	Ziel-URL des aktuellen Detaildatensatzes in einer anderen Sprache
Translation\TranslationOverlayResolver	feldstatusbewusste Wertauflösung
Review\SourceFingerprintCalculator	deterministischer Fingerabdruck des übersetzbaren Quellzustands

Keine Erweiterungspunkte

DCA-Callback-Klassen (Backend\*), Event-Listener und Hook-Klassen (EventListener\*), Route-Dekoratoren (Routing\*), Storage-Implementierungen (Database*), die DI-Extension, die Bundle-Klasse und die Konsolenbefehle. Diese dürfen weder erweitert noch ersetzt werden.

Protokollierung

Das Paket registriert drei eigene Monolog-Kanäle:

Kanal	Inhalt
contao_multilingual_pagetree	Betriebsereignisse des Pakets
contao_multilingual_pagetree_integrity	Integritätsscan, Reparaturplanung und Cascade-Ausführung
contao_multilingual_pagetree_license	ausschließlich ausdrücklich ausgelöste Lizenzvorgänge

Der Lizenzkanal schreibt nach var/logs/license.log ab Level info. Der Stream-Handler legt die Datei erst beim ersten geschriebenen Eintrag an — bei Installation, Contao-Setup, Container-Kompilierung und normalem Rendering entsteht also keine Datei. Protokolliert werden Ergebniskategorien und Referenzen, keine Schlüssel und keine vollständigen Antwortinhalte.

Deployment und Cache

composer install --no-dev --optimize-autoloader
vendor/bin/contao-console contao:migrate
vendor/bin/contao-console cache:clear --env=prod
vendor/bin/contao-console cache:warmup --env=prod

Externe Kommunikation findet ausschließlich bei ausdrücklich ausgelösten Lizenzvorgängen sowie am serverseitig authentifizierten Aktualisierungsendpunkt statt. Frontend-Auslieferung und redaktionelle Arbeit laufen ohne externe Aufrufe.

Fehlerbehebung

Symptom	Ursache und Prüfung
Das Globus-Symbol fehlt am Website-Startpunkt	Die Aktion erscheint nur an Seiten vom Typ Website-Startpunkt und nur, wenn Sie diesen Startpunkt verwalten dürfen. Seitenrechte prüfen.
Zusätzliche Sprachen lassen sich nicht anlegen	Keine gültige Lizenz an diesem Startpunkt: „Für die Verwaltung zusätzlicher Sprachen ist eine gültige Lizenz erforderlich.“ Lizenzstatus und konfigurierte Domain prüfen.
Lizenz wird abgewiesen, obwohl der Schlüssel stimmt	Die Lizenz ist an die exakte Domain gebunden: „Die Lizenz stimmt nicht mit der exakten Domain dieses Startpunkts überein.“ www-Variante und Subdomain prüfen.
Meldung Aktualisierung erforderlich	Der gespeicherte Status stammt aus einem älteren Lizenzformat. Einmalig Lizenz aktualisieren ausführen; der bisherige Status bleibt bis dahin unverändert.
Meldung Fehlende Domain bei der Aktivierung	„Konfigurieren Sie vor der Aktivierung die Domain des Website-Startpunkts.“
Speichern einer Sprach-URL wird abgelehnt	Hostname und Einstiegspfad sind bereits vergeben oder mehrdeutig. Die Meldung nennt den konkreten Fall — siehe Sprach-URL.
Sprach-URL greift nicht	Zuordnungen und Pfadpräfixe werden zwischengespeichert. Cache neu aufbauen, dann Domain- und Einstiegspfad-Feld prüfen.
Sprache über eigene Domain nicht erreichbar	Der Hostname wird exakt verglichen. www-Varianten und übergeordnete Domains gelten nicht.
Sprache landet unerwartet unter /xx statt im Stammverzeichnis	Leerer Einstiegspfad und / sind nicht dasselbe. Ohne eigene Domain bedeutet leer: Sprachcode als Präfix.
Übersetzungen erscheinen nicht im Frontend	Veröffentlichung der Sprache und Seitenverfügbarkeit prüfen; bei Inhalten zusätzlich den Inhaltsübersetzungsmodus.
Backend zeigt die Ausgangssprache statt der gewählten Sprache	Das Backend nennt die Kategorie des Grundes — siehe Berechtigungen.
Ein Inhaltselement zeigt in der Zielsprache weiterhin den Quelltext	Ein unverändert übernommener Text bleibt mit der Ausgangssprache verbunden. Text ändern und speichern, damit er zur Übersetzung wird.
Elementtyp oder Bildauswahl sind nicht bearbeitbar	Strukturfelder werden im verbundenen Modus von der Ausgangssprache bestimmt. Für eine eigenständige Struktur den Modus Freier Sprachinhalt wählen.
Ein Feld einer Fremd-Erweiterung ist nicht übersetzbar	Übersetzt wird nur, was registriert ist. Feld über TranslationFieldPolicyContributorInterface registrieren.
Moduswechsel lässt sich nicht speichern	Das Feld Moduswechsel bestätigen ist nicht gesetzt, oder die Berechtigung fehlt: „Sie dürfen den Inhaltsübersetzungsmodus nicht ändern.“
Meldung „Diese Aktion muss abgesendet und darf nicht als Link geöffnet werden.“	Die Aktion wurde als Link statt als Formular aufgerufen. Schreibende Aktionen laufen über POST mit Anfrage-Token.
Unerwartete Datenlage	integrity:scan ausführen und die Vorschau prüfen, bevor eine Reparatur bestätigt wird.

Notieren Sie bei einer Lizenzfehlermeldung die angezeigte Referenz und geben Sie sie an die Administration weiter. Lizenzschlüssel, Antwortinhalte und Zugangsdaten gehören nicht in Tickets, Screenshots oder Protokolle.

Bekannte Einschränkungen

• Für Inhaltselemente wird eine Übersetzung nur in Feldern gespeichert, für die eine Spalte in der Übersetzungsablage besteht. Felder aus Fremd-Erweiterungen werden im gewohnten Formular angezeigt, sind aber erst nach Registrierung über den vorgesehenen Erweiterungspunkt übersetzbar.
• Wird eine Sprache nachträglich auf eine eigene Domain umgestellt, verlieren zuvor gültige Adressen mit Sprachcode ihre Route. Für dauerhafte Weiterleitungen sind eine Contao-Weiterleitungsseite oder eine Webserver-Regel vorgesehen.
• Die Integritätsreparatur löst mehrdeutige Beziehungen nicht selbstständig auf.
• Das Paket setzt Contao 5 voraus; Contao 4 wird nicht unterstützt.

Deinstallation

Sichern Sie vor Änderungen Datenbank und Dateien. Deaktivieren Sie zuerst redaktionelle Änderungen und prüfen Sie den Datenbestand mit data-report beziehungsweise integrity:scan. Das Entfernen des Composer-Pakets löscht keine gespeicherten Übersetzungsdaten automatisch.

Proprietär. Copyright: V&T Innovations Team, www.v-t.one.