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. Am stärksten trifft es die Redaktion, die täglich damit arbeitet — und danach die Administration, die die Abweichungen hinterher wieder einfangen muss.

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, ohne dass Daten verloren gehen.
• 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.
Die Übersetzungen sollen maschinell erzeugt werden	Nicht dieses Paket. Es liefert Struktur, Formulare und Prüfstatus — aber keine automatische Übersetzung.
Es gibt keinen Shell-Zugriff auf den Server	Die redaktionelle Arbeit läuft vollständig im Backend. Für die Datenprüfung und -reparatur brauchen Sie jedoch die Konsole.

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 beziehungsweise Bedingung
PHP	^8.1
Contao	^5.0 (contao/core-bundle)
Composer	für Installation und Aktualisierung
Ausgehendes HTTPS vom Server	erforderlich für die Lizenzaktivierung
Ein privates Verzeichnis unterhalb von var/	muss für den Webserver beschreibbar sein

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

So bereiten Sie die Installation vor

1. Sichern Sie die Datenbank und das Verzeichnis files/.
2. Prüfen Sie die Systemvoraussetzungen aus der Tabelle oben.
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. Entscheiden Sie vorab über das URL-Muster: gleiche Domain mit Pfadpräfixen, getrennte Domains oder eine Mischung. Ein späterer Wechsel ändert bestehende Adressen.
6. Tragen Sie an jedem Website-Startpunkt die korrekte primäre Domain ein. Ohne sie lässt sich später keine Lizenz aktivieren.
7. Installieren und prüfen Sie zuerst auf einer Testumgebung mit einer Kopie der Produktivdaten.

Das Paket legt seine Betriebsdaten in einem privaten Verzeichnis unterhalb von var/ ab — also außerhalb des öffentlichen Webverzeichnisses und nicht über HTTP erreichbar. Dieses Verzeichnis muss für den Webserver beschreibbar sein und gehört in die Datensicherung. Dass es noch nicht existiert, 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.

So installieren Sie das Paket im Contao Manager

1. Öffnen Sie den Contao Manager und melden Sie sich an.
2. Öffnen Sie den Bereich Entdecken. Neue Pakete werden immer dort gesucht und hinzugefügt; der Bereich Pakete daneben zeigt unter Installierte Pakete nur, was bereits vorhanden ist. Entdecken ist zugleich die Startansicht des Contao Managers.
3. Suchen Sie über Pakete suchen nach vtinnovations/contao-multilingual-pagetree und wählen Sie beim Treffer Paket hinzufügen. Der Hinweis „Dieses Paket wird installiert, wenn du die Änderungen anwendest.“ bestätigt die Vormerkung.
4. Wenden Sie die Änderungen an. Der Contao Manager installiert das Paket und aktualisiert den Autoloader.
5. Wechseln Sie anschließend in den Bereich Systemwartung, dort zu Datenbank-Migrationen und -Backups, und führen Sie Datenbank prüfen aus. Bestätigen Sie die angezeigten Datenbank-Änderungen.
6. Wiederholen Sie Datenbank prüfen ein zweites Mal. Der zweite Durchlauf muss ohne weitere Änderungen enden.
7. Leeren Sie zuletzt unter Systemwartung den Anwendungs-Cache (in der Navigation auch als Cache erneuern erreichbar).

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

So prüfen Sie, ob die Installation gelungen ist

1. Lassen Sie die Konsolenbefehle des Pakets auflisten:

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

   Erscheinen die Befehle, ist das Bundle registriert und der Dienstcontainer wurde erfolgreich übersetzt.
2. Öffnen Sie im Backend die Seitenstruktur.
3. Prüfen Sie, ob in der Zeile jedes Website-Startpunkts die Aktion Zusätzliche Sprachen verwalten (Globus-Symbol) erscheint.
4. Bearbeiten Sie einen Website-Startpunkt und prüfen Sie, ob der Abschnitt Contao Multilingual Pagetree Licence management vorhanden ist.

Lizenz aktivieren

Die Lizenz wird je Website-Startpunkt verwaltet, im Abschnitt Contao Multilingual Pagetree Licence management der Seiteneinstellungen dieses Startpunkts. Die Aktivierung setzt eine Administrator-Sitzung im Contao-Backend voraus sowie ausgehendes HTTPS vom Server — nicht vom Browser.

So aktivieren Sie die Lizenz eines Startpunkts

1. Stellen Sie sicher, dass am Contao-Website-Startpunkt die korrekte primäre Domain eingetragen ist. Fehlt sie, zeigt der Bereich Fehlende Domain mit dem Hinweis „Konfigurieren Sie vor der Aktivierung die Domain des Website-Startpunkts.“
2. Öffnen Sie Seitenstruktur und bearbeiten Sie den Website-Startpunkt.
3. Gehen Sie zum Abschnitt Contao Multilingual Pagetree Licence management.
4. Tragen Sie den Schlüssel in das Feld Lizenzschlüssel ein.
5. Wählen Sie Lizenz aktivieren und warten Sie, bis die Seite neu geladen ist. Der Vorgang läuft innerhalb der Anfrage; schließen Sie den Reiter währenddessen nicht.
6. Bei Erfolg meldet das Backend „Lizenz aktiviert.“ und Lizenzstatus steht auf Aktiv.
7. Prüfen Sie zur Kontrolle Domain des Website-Startpunkts, Lizenzdomain, Lizenzlaufzeit (Lebenslang) und Aktivierungsstatus.
8. Wiederholen Sie die Schritte für jeden weiteren Website-Startpunkt.

Im Lizenzbereich stehen diese Schaltflächen zur Verfügung:

Schaltfläche	Zweck
Lizenz aktivieren	erstmalige Aktivierung dieses Website-Startpunkts
Lizenz ersetzen	einen vorhandenen Schlüssel durch einen anderen ersetzen
Lizenz aktualisieren	den Lizenzstatus dieses Startpunkts erneuern
Lizenz prüfen	meldet bei Erfolg „Die gespeicherte Lizenz ist unversehrt und für diesen Website-Startpunkt gültig.“
Lizenz entfernen	entfernt die hinterlegte Lizenz dieses Startpunkts; bestätigt mit „Entfernen der Lizenz bestätigen? Mehrsprachige Daten bleiben unverändert.“

Die möglichen Statusanzeigen:

Lizenzstatus	Bedeutung
Aktiv	Die Lizenz gilt für diesen Startpunkt.
Nicht aktiviert	„Für diesen Website-Startpunkt ist noch keine Lizenz hinterlegt.“
Falsche Domain	„Die Lizenz stimmt nicht mit der exakten Domain dieses Startpunkts überein.“
Fehlende Domain	„Konfigurieren Sie vor der Aktivierung die Domain des Startpunkts.“
Falsches Projekt	„Die Lizenz gehört zu einem anderen Projekt.“
Falsches Paket	„Dies ist nicht die lebenslange Lizenz, die dieses Produkt benötigt.“
Noch nicht gültig / Abgelaufen	„Die Lizenz ist noch nicht gültig.“ beziehungsweise „Die Lizenz ist abgelaufen.“
Aktualisierung erforderlich	„Die gespeicherte Lizenz stammt aus einem älteren Lizenzformat. Führen Sie einmalig ‚Lizenz aktualisieren‘ aus; die gespeicherte Lizenz bleibt bis dahin unverändert.“
Prüfung nicht verfügbar	Der Lizenzdienst war nicht erreichbar. Der gespeicherte Stand bleibt unverändert.

Zielsprachen anlegen

Die Zielsprachen eines Startpunkts werden über die Aktion Zusätzliche Sprachen verwalten (Globus-Symbol) in der Seitenstruktur gepflegt. Die Aktion erscheint nur an Seiten vom Typ Website-Startpunkt und nur, wenn Sie diesen Startpunkt verwalten dürfen.

So legen Sie eine Zielsprache an

1. Speichern Sie den Website-Startpunkt und kehren Sie in die Seitenstruktur zurück.
2. Klicken Sie in der Zeile des Startpunkts auf Zusätzliche Sprachen verwalten (Globus-Symbol).
3. Wählen Sie Sprache hinzufügen („Eine zusätzliche Zielsprache zu diesem Startpunkt hinzufügen“).
4. Wählen Sie im Abschnitt Spracheinstellungen die Sprache. Sprachcode, Sprachbezeichnung und eine Standard-Flagge werden automatisch gesetzt; Bezeichnung und Flagge lassen sich ändern.
5. Legen Sie im Abschnitt Sprach-URL fest, unter welcher Adresse die Sprache erreichbar sein soll — siehe Sprach-URL. Alle drei Felder dürfen leer bleiben.
6. Entscheiden Sie im Abschnitt Seitenverfügbarkeit über Seitenverfügbarkeit, Inhaltsübersetzungsmodus und Inhaltsstrukturmodus.
7. Setzen Sie im Abschnitt Veröffentlichung die Option Veröffentlichen („Diese Sprache im Frontend verfügbar machen.“) und speichern Sie.
8. Wiederholen Sie Schritt 3 bis 7 für jede weitere Zielsprache.

Die native Contao-Sprache des Startpunkts ist die Standard-/Ausgangssprache und wird hier nicht erneut angelegt. Die Sichtbarkeit einer Sprache lässt sich in der Liste auch direkt über Sichtbarkeit umschalten ändern.

Mitgelieferte Flaggen: at, br, de, en, es, fr, gb, it, ja, jp, nl, pl, pt, ru, us, zh.

Erste Übersetzung

So übersetzen Sie einen ersten Datensatz

1. Öffnen Sie eine Seite, einen Artikel, eine Nachricht, einen Termin oder eine FAQ im gewohnten Bearbeitungsformular.
2. Wählen Sie oberhalb des Formulars das Sprachregister der Zielsprache.
3. Füllen Sie die übersetzbaren Felder aus. Für Seiten sind das Seitenname, Seitenalias, Seitentitel und Beschreibung der Seite.
4. Stellen Sie je Feld den Übersetzungsstatus ein, falls die Vorbelegung nicht passt — siehe Übersetzungsstatus je Feld.
5. Speichern Sie. Der Datensatz der Ausgangssprache bleibt dabei unverändert.
6. Rufen Sie die Seite im Frontend unter der Adresse der Zielsprache auf und kontrollieren Sie das Ergebnis.

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

Sprachwechsler einbinden

So binden Sie den Sprachwechsler ein

1. Öffnen Sie Layout → Module und legen Sie ein neues Modul an.
2. Wählen Sie den Modultyp Contao Multilingual Pagetree Sprachwechsler aus der Kategorie Verschiedenes.
3. Wählen Sie Darstellung des Sprachumschalters — Flaggen, Beschriftungen oder beides, horizontal oder vertikal.
4. Wählen Sie unter Nicht verfügbare Sprachen, ob solche Sprachen ausgeblendet oder deaktiviert angezeigt werden.
5. Entscheiden Sie über Aktive Sprache ausblenden.
6. Speichern Sie und binden Sie das Modul im Seitenlayout ein — oder als Inhaltselement vom Typ Modul einfügen.
7. Prüfen Sie im Frontend, dass der Wechsel zwischen den Sprachen auf derselben Seite bleibt.

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

Die Spracheinstellungen eines Startpunkts liegen unter Seitenstruktur → Zeile des Website-Startpunkts → Zusätzliche Sprachen verwalten. Das Formular je Sprache ist in vier Abschnitte gegliedert.

So ändern Sie eine bestehende Sprache

1. Öffnen Sie Zusätzliche Sprachen verwalten am Website-Startpunkt.
2. Wählen Sie in der Liste bei der gewünschten Sprache Sprache bearbeiten.
3. Ändern Sie die Felder und speichern Sie.
4. Bauen Sie nach Änderungen an den Sprach-URL-Feldern den Anwendungs-Cache neu auf.

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

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.

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.

So richten Sie eine eigene Sprach-URL ein

1. Legen Sie zuerst fest, welches Muster die Website insgesamt verwenden soll: gleiche Domain mit Pfadpräfixen, getrennte Domains oder eine Mischung. Entscheiden Sie das für alle Sprachen gemeinsam, nicht je Sprache nacheinander.
2. Richten Sie zusätzliche Hostnamen im DNS und auf dem Webserver ein und lassen Sie sie auf dieselbe Contao-Installation zeigen.
3. Öffnen Sie den Sprachdatensatz über Zusätzliche Sprachen verwalten → Sprache bearbeiten.
4. Wählen Sie unter Protokoll in der Regel Von der Website-Wurzel übernehmen. Setzen Sie HTTPS oder HTTP nur, wenn diese Sprache bewusst abweichen soll.
5. Tragen Sie unter Domain nur den Hostnamen ein, ohne Protokoll, Pfad und Port — oder lassen Sie das Feld leer, um die Domain des Startpunkts zu verwenden.
6. Tragen Sie unter Einstiegspfad das Pfadpräfix ein, etwa /de — oder /, wenn die Sprache im Stammverzeichnis ihrer Domain liegen soll.
7. Speichern Sie. Wird die Eingabe abgewiesen, nennt die Meldung den Konflikt (siehe Tabelle unten); korrigieren Sie und speichern Sie erneut.
8. Bauen Sie anschließend den Anwendungs-Cache neu auf — Zuordnungen und Pfadpräfixe werden zwischengespeichert.
9. Rufen Sie jede Sprache im Frontend unter ihrer neuen Adresse auf.

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.
Pfad, Query-String, Fragment oder Port im Domain-Feld	Bitte geben Sie nur einen Hostnamen ohne Pfad ein. — … ohne Query-String ein. — … ohne Fragment ein. — … ohne Port ein.
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.
Doppelte Schrägstriche im Einstiegspfad	Der Einstiegspfad darf keine wiederholten Schrägstriche 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.“) steht im Abschnitt Seitenverfügbarkeit des Sprachdatensatzes und gilt je Zielsprache. Die Ausgangssprache wird hier nicht als Sprachdatensatz geführt und verwendet immer den Quellseitenbaum.

So stellen Sie das Verhalten für nicht übersetzte Seiten ein

1. Öffnen Sie den Sprachdatensatz über Zusätzliche Sprachen verwalten → Sprache bearbeiten.
2. Wählen Sie im Abschnitt Seitenverfügbarkeit das gleichnamige Feld.
3. Entscheiden Sie zwischen Seiten ohne Übersetzung ausblenden und Standardseite anzeigen.
4. Speichern Sie und bauen Sie den Anwendungs-Cache neu auf.
5. Rufen Sie im Frontend eine bewusst nicht übersetzte Seite in dieser Sprache auf und prüfen Sie das Ergebnis.

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

Inhaltsstrukturmodus

Der Inhaltsstrukturmodus steht im Abschnitt Seitenverfügbarkeit des Sprachdatensatzes und bestimmt, ob die Zielsprache der Struktur der Ausgangssprache folgt oder eine eigene besitzt. Der freie Modus setzt eine gültige Lizenz voraus.

Option	Hilfetext im Backend
Verbundene Übersetzung (Standard)	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.

So wechseln Sie den Inhaltsstrukturmodus

1. Sichern Sie die Datenbank. Der Wechsel löscht zwar nichts, ändert aber, welche Inhalte ausgegeben werden.
2. Planen Sie den Wechsel möglichst früh — am besten, solange in dieser Sprache noch keine Inhalte des jeweils anderen Modus gespeichert sind.
3. Öffnen Sie den Sprachdatensatz über Zusätzliche Sprachen verwalten → Sprache bearbeiten.
4. Wählen Sie im Feld Inhaltsstrukturmodus den neuen Modus. Das Formular lädt sich sofort neu.
5. Speichern Sie.
6. Erscheint eine Meldung nach dem Muster „Durch Aktivieren von [Modus] für [Sprache] bleiben n verbundene Übersetzungsdatensätze und n freie Datensätze gespeichert, aber n davon werden nicht mehr ausgegeben.“, wurde der Wechsel nicht übernommen — der bisherige Modus bleibt gespeichert. Lesen Sie dazu den Hinweis unten.
7. Prüfen Sie nach einem erfolgreichen Wechsel die betroffenen Seiten im Frontend.

Fehlt Ihnen die Berechtigung, meldet das Backend „Sie dürfen den Inhaltsübersetzungsmodus nicht ändern.“ Dieselbe Meldung erscheint beim Wechsel zum freien Modus, wenn keine gültige Lizenz vorliegt. Der Wechsel zurück zur verbundenen Übersetzung bleibt auch ohne Lizenz möglich.

Inhaltsübersetzungsmodus

Getrennt von der Seitenverfügbarkeit legt der Inhaltsübersetzungsmodus fest, „wie nicht übersetzte Inhalte in dieser Sprache dargestellt werden“. Das Feld steht im selben Abschnitt Seitenverfügbarkeit des Sprachdatensatzes.

So stellen Sie den Inhaltsübersetzungsmodus ein

1. Öffnen Sie den Sprachdatensatz über Zusätzliche Sprachen verwalten → Sprache bearbeiten.
2. Wählen Sie im Feld Inhaltsübersetzungsmodus die gewünschte Option.
3. Speichern Sie und bauen Sie den Anwendungs-Cache neu auf.
4. Rufen Sie eine Seite mit teilweise übersetzten Inhalten in dieser Sprache auf und prüfen Sie, ob die nicht übersetzten Elemente wie gewünscht erscheinen oder fehlen.

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

Ü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

So prüfen Sie, ob ein bestimmtes Feld übersetzbar ist

1. Öffnen Sie den Datensatz im Backend und wechseln Sie auf das Register der Zielsprache.
2. Suchen Sie das Feld. Erscheint bei Seiten, Artikeln, Nachrichten, Terminen und FAQ daneben das Auswahlfeld Übersetzungsstatus, ist das Feld übersetzbar.
3. Bei Inhaltselementen gilt die Tabelle oben: Was dort nicht steht, wird von der Ausgangssprache bestimmt.
4. Fehlt ein Feld einer Fremd-Erweiterung, lässt es sich nachträglich registrieren — siehe Erweiterungspunkte.

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.“ Es steht direkt beim jeweiligen Feld im Sprachregister.

So setzen Sie den Übersetzungsstatus eines Feldes

1. Öffnen Sie den Datensatz und wechseln Sie auf das Register der Zielsprache.
2. Vergleichen Sie den eingetragenen Wert mit dem daneben angezeigten Aktuellen Ausgangswert.
3. Wählen Sie im Auswahlfeld Übersetzungsstatus die passende Option.
4. Tragen Sie bei Eigene Übersetzung verwenden den übersetzten Text ein.
5. Speichern Sie.
6. Prüfen Sie das Ergebnis im Frontend. Bei Aus Ausgangssprache übernehmen ändert sich der Wert künftig automatisch mit der Ausgangssprache mit.

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.

Inhaltselemente übersetzen

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

So übersetzen Sie ein Inhaltselement

1. Öffnen Sie den Artikel und darin das Inhaltselement im gewohnten Bearbeitungsformular.
2. Wählen Sie oben im Formular das Sprachregister der Zielsprache. Das aktive Register zeigt, welche Sprache Sie bearbeiten.
3. Das Formular zeigt zunächst den Text der Ausgangssprache. Ändern Sie ihn in die Zielsprache.
4. Speichern Sie. Erst jetzt existiert eine Übersetzung für dieses Feld.
5. Prüfen Sie im Frontend unter der Adresse der Zielsprache.
6. Kehren Sie über das Sprachregister zur Ausgangssprache zurück und vergewissern Sie sich, dass dort nichts verändert wurde.

Es gibt hier keine zusätzlichen Auswahlfelder pro Feld und keinen gesonderten Abschnitt für übersetzbare Inhalte. 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 im Sprachregister, ob eine Übersetzung nach einer Änderung der Ausgangssprache erneut zu prüfen ist. Der Prüf-Workflow setzt eine gültige Lizenz voraus.

So markieren Sie eine Übersetzung als geprüft

1. Öffnen Sie den Datensatz und wechseln Sie auf das Register der Zielsprache.
2. Lesen Sie den Prüfstatus. Steht dort Prüfung erforderlich, hat sich die Ausgangssprache seit der letzten Prüfung geändert.
3. Sehen Sie sich unter Geänderte Quellfelder an, welche Felder betroffen sind.
4. Vergleichen Sie je Feld Geprüfter Quellwert mit Aktueller Quellwert.
5. Passen Sie die Übersetzung an, wo es nötig ist, und speichern Sie.
6. Wählen Sie Übersetzung als geprüft markieren („Den aktuellen Stand der Quelle als geprüft speichern.“).
7. Das Backend meldet „Die Übersetzung wurde als geprüft markiert.“ und der Status wechselt auf Aktuell. Geprüft am und Geprüft von werden fortgeschrieben.

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.

Integritätsprüfung und Reparatur

Das Paket prüft seinen eigenen Datenbestand auf Widersprüche: verwaiste Übersetzungen, doppelte Aliase, Beziehungen über Website- oder Sprachgrenzen hinweg, ungültige Sprachkonfigurationen. Die Prüfung ist immer verfügbar; das Ausführen von Reparaturen setzt eine gültige Lizenz am betroffenen Startpunkt voraus.

So prüfen und reparieren Sie den Datenbestand

1. Sichern Sie die Datenbank.
2. Lassen Sie zuerst nur prüfen — dieser Schritt schreibt nichts:

   vendor/bin/contao-console contao-multilingual-pagetree:integrity:scan

3. Grenzen Sie bei Bedarf ein, etwa auf einen Startpunkt (--root=<id>), eine Sprache (--language=de) oder eine Mindestschwere (--severity=error).
4. Lesen Sie den Bericht. Jeder Befund nennt eine Schwere und ob er reparierbar ist.
5. Lassen Sie sich die geplanten Reparaturen als Testlauf anzeigen — ohne --execute wird nichts geschrieben:

   vendor/bin/contao-console contao-multilingual-pagetree:integrity:repair --root=<id>

6. Prüfen Sie die Vorschau Zeile für Zeile.
7. Führen Sie die Reparatur erst danach aus. --root ist dabei Pflicht:

   vendor/bin/contao-console contao-multilingual-pagetree:integrity:repair --root=<id> --execute

8. Löschende Aktionen werden auch jetzt noch übersprungen; sie verlangen zusätzlich --force. Setzen Sie es nur, wenn Sie die Vorschau geprüft haben und eine aktuelle Sicherung vorliegt.
9. Führen Sie den Scan aus Schritt 2 erneut aus und vergewissern Sie sich, dass die Befunde verschwunden sind.

Der Bericht kennt vier Schweregrade und vier Aussagen zur Reparaturfähigkeit:

Schweregrade	Reparaturfähigkeit
Information	Keine Reparatur verfügbar
Warnung	Wird automatisch repariert
Fehler	Reparatur erfordert Bestätigung
Kritisch	Manuelle Entscheidung erforderlich

Die beiden Spalten sind voneinander unabhängig: Ein Befund beliebiger Schwere kann jede der vier Reparaturfähigkeiten tragen.

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

Mehrdeutige Beziehungen werden nie automatisch geraten oder zusammengeführt: Sie werden gemeldet und einer redaktionellen Entscheidung überlassen. Die vollständigen Optionen beider Befehle stehen unter Konsolenbefehle.

Sprachwechsler-Modul

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

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

Option	Hilfetext und Werte
Nicht verfügbare Sprachen	„Legt fest, wie Sprachen dargestellt werden, in denen die aktuelle Seite oder der aktuelle Detaildatensatz nicht verfügbar ist.“ — 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.“

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.

Hierfür gibt es keine eigene Einstellung. Die Ausgabe folgt unmittelbar der Sprach-URL-Konfiguration: Ist die Adresse einer Sprache richtig konfiguriert, sind auch ihre Metadaten richtig. Zum Prüfen rufen Sie eine Seite im Frontend auf und sehen sich im Quelltext die link-Elemente mit rel="canonical" und rel="alternate" an.

Berechtigungen und Lizenzumfang

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 Benutzerberechtigung 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
Ungültiger Sprachcode angefordert	Die angeforderte Sprache ist kein gültiger Sprachcode, daher wird die Ausgangssprache angezeigt.
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 gültige Lizenz an einem Startpunkt gilt dort für den Funktionsumfang:

Funktion	Ohne Lizenz	Mit Lizenz
Zusätzliche Sprachen anlegen und bearbeiten	nicht verfügbar	verfügbar
Übersetzungen anlegen und bearbeiten	nicht verfügbar	verfügbar
Redaktioneller Prüfstatus	nicht verfügbar	verfügbar
Wechsel zum freien Sprachinhalt	nicht verfügbar	verfügbar
Rückkehr zur verbundenen Übersetzung	verfügbar	verfügbar
Integritätsprüfung (integrity:scan)	verfügbar	verfügbar
Integritätsreparatur ausführen	nicht verfügbar	verfügbar
Frontend-Ausgabe bereits vorhandener Übersetzungen	verfügbar	verfügbar
Sprachwechsler, kanonische URLs und hreflang	verfügbar	verfügbar

Teil 3 — Für Entwickler

Konsolenbefehle

Für den mehrsprachigen Datenbestand stehen drei Befehle bereit:

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

integrity:scan

„Scans multilingual records for integrity issues (read-only).“ Der Scan verändert keine Daten. Die Ausgabe enthält nur Codes, Tabellen, IDs und Zählwerte — nie übersetzte Inhalte. Der Rückgabewert spiegelt die höchste gefundene Schwere: 0 ohne Befunde, 1 bei nicht blockierenden, 2 bei blockierenden Befunden, 3 bei einem Abbruch.

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)

integrity:repair

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

Option	Bedeutung
--root	Limit the repair to one root page id — bei --execute zwingend
--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). Der Befehl zählt die gespeicherten Datensätze je Ablage und weist darauf hin, dass das Entfernen des Composer-Pakets keinen davon löscht. Gibt es noch keine Daten, meldet er „No multilingual data is stored yet.“

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 Verwaltungstabelle, keine Backend-Oberfläche

Dateiseitig schreibt das Paket ausschließlich in ein privates Verzeichnis unterhalb von var/, also außerhalb des öffentlichen Webverzeichnisses. Es muss für den Webserver beschreibbar sein und gehört in die Datensicherung.

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

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 eigene Monolog-Kanäle, damit sich seine Ereignisse routen und filtern lassen, ohne die übrige Contao-Protokollierung anzufassen:

Kanal	Inhalt
contao_multilingual_pagetree	Betriebsereignisse des Pakets
contao_multilingual_pagetree_integrity	Integritätsscan, Reparaturplanung und Cascade-Ausführung

Protokolliert werden Ergebniskategorien, Codes und Referenzen — keine übersetzten Inhalte und keine Zugangsdaten.

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

Frontend-Auslieferung und redaktionelle Arbeit laufen ohne externe Aufrufe. Ausgehende Verbindungen entstehen nur, wenn eine Administratorin oder ein Administrator im Backend ausdrücklich einen Lizenzvorgang auslöst.

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 Falsches Paket	„Dies ist nicht die lebenslange Lizenz, die dieses Produkt benötigt.“ Der Schlüssel gehört zu einem anderen V-T.ONE-Produkt.
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.“
Meldung Prüfung nicht verfügbar	Der Lizenzdienst war nicht erreichbar. Ausgehendes HTTPS vom Server prüfen und den Vorgang später wiederholen; der gespeicherte Stand bleibt unverändert.
Es ist bereits eine Lizenz hinterlegt, der Schlüssel soll gewechselt werden	„Für diesen Website-Startpunkt ist bereits eine Lizenz hinterlegt. Verwenden Sie ‚Lizenz ersetzen‘, um den Schlüssel zu ändern.“
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 und Lizenzumfang.
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 — siehe Inhaltselemente übersetzen.
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	Entweder fehlt die Berechtigung („Sie dürfen den Inhaltsübersetzungsmodus nicht ändern.“) oder es würden bereits gespeicherte Datensätze aufhören zu rendern — siehe Inhaltsstrukturmodus.
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.
Reparatur bricht mit „Executing repairs requires an explicit --root=<id>.“ ab	--execute verlangt zwingend einen Startpunkt — siehe Integritätsprüfung und Reparatur.
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 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.
• Integritätsprüfung und -reparatur haben keine Oberfläche im Contao-Backend; beide laufen ausschließlich über die Konsole und setzen Shell-Zugriff voraus.
• Ein Wechsel des Inhaltsstrukturmodus wird abgewiesen, sobald bereits gespeicherte Datensätze dadurch aufhören würden zu rendern. Es gehen keine Daten verloren, der Wechsel lässt sich in dieser Lage aber nicht im laufenden Betrieb durchführen.
• 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 übersetzt nicht selbst: Es liefert Struktur, Formulare und Prüfstatus, aber keine maschinelle Übersetzung.
• Das Paket setzt Contao 5 voraus; Contao 4 wird nicht unterstützt.

Deinstallation

Das Entfernen des Composer-Pakets löscht keine gespeicherten Übersetzungsdaten. Das Löschen mehrsprachiger Daten ist immer eine ausdrückliche, getrennte Handlung.

So entfernen Sie das Paket

1. Sichern Sie Datenbank und Dateien.
2. Verschaffen Sie sich einen Überblick über den Datenbestand:

   vendor/bin/contao-console contao-multilingual-pagetree:data-report

3. Entfernen Sie die Sprachwechsler-Module aus den Seitenlayouts, damit im Frontend keine leeren Bereiche zurückbleiben.
4. Entfernen Sie an jedem Website-Startpunkt die Lizenz über Lizenz entfernen, falls die Installation nicht weiterbetrieben wird. Mehrsprachige Daten bleiben dabei unverändert.
5. Entfernen Sie das Paket — im Contao Manager unter Pakete → Installierte Pakete, oder auf der Kommandozeile:

   composer remove vtinnovations/contao-multilingual-pagetree

6. Bauen Sie den Anwendungs-Cache neu auf.
7. Die Tabellen des Pakets bleiben bestehen und werden nie automatisch entfernt. Löschen Sie sie nur bewusst und nach einer Sicherung.
8. Löschen Sie das Verzeichnis var/contao-multilingual-pagetree/, wenn die Installation endgültig nicht weiterbetrieben wird.

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