Lernseite · Mehrsprachigkeit und Übersetzungen
Eine Website in mehreren Sprachen: Inhalte, Beschriftungen und Zeichensätze
Die Redaktion übersetzt Seiten und Inhalte im Backend, die Integratorin sorgt dafür, dass feste Beschriftungen wie „Weiterlesen“ in jeder Sprache erscheinen. Auf dieser Seite machst du eine Website dreisprachig, von der Site-Konfiguration über XLIFF-Dateien bis zum Sprachumschalter. Am Ende verstehst du auch, warum aus einem ä manchmal zwei seltsame Zeichen werden.
Die Musikschule wird dreisprachig
Die Integratorin Mara baut die Website der Musikschule Lindenau mit TYPO3 14.3 und einem eigenen Sitepackage lindenau_site. Die Website ist auf Deutsch. Dazu kommen Englisch für internationale Studierende und Polnisch, weil viele Familien aus dem Nachbarland ihre Kinder anmelden.
Mara unterscheidet zwei Arten von Text:
- Inhalte schreibt die Redaktion: Seiten, Inhaltselemente, Datensätze wie News oder Kurse und die Metadaten von Bildern. Sie stehen in der Datenbank und werden im Backend übersetzt.
- Beschriftungen, auch Labels genannt, stecken in Templates und Extensions, etwa „Kurs anmelden“ oder „Kontakt“. Sie stehen in XLIFF-Dateien und werden dort übersetzt.
Eine Extension für Mehrsprachigkeit braucht Mara nicht. TYPO3 kann Inhalte, Datensätze und Metadaten von Haus aus in beliebig vielen Sprachen verwalten.
Sprachen in der Site-Konfiguration
Welche Sprachen eine Website hat, steht in der Site-Konfiguration, nicht im Page TSconfig oder in der .htaccess. Im Backend bearbeitest du sie im Bereich „Sites“ im Modul „Setup“, im Reiter „Languages“. Gespeichert wird sie als Datei config.yaml im Ordner config/sites.
Jede Sprache hat diese wichtigen Angaben:
- languageId ist die Nummer der Sprache. Die Standardsprache hat immer die 0, weitere Sprachen bekommen höhere Zahlen. Sobald es Inhalte gibt, darf sich die Nummer nicht mehr ändern.
- title ist der Name im Backend, navigationTitle der Name im Sprachmenü.
- base ist der Einstieg der Sprache, zum Beispiel das Präfix „en“ oder eine eigene Domain.
- locale steuert unter anderem Datums- und Zahlenformate, etwa
pl_PL.UTF-8. - hreflang ist die Sprachangabe für Suchmaschinen. TYPO3 leitet sie aus dem Locale ab, du kannst sie aber überschreiben.
- flag wählt die Flagge, die das Backend neben der Sprache zeigt.
- enabled schaltet die Sprache im Frontend ein oder aus. Im Backend kann man trotzdem schon übersetzen.
languages:
- languageId: 0
title: Deutsch
base: /
locale: de_DE.UTF-8
flag: de
- languageId: 1
title: English
base: /en/
locale: en_GB.UTF-8
flag: gb
fallbackType: strict
- languageId: 2
title: Polski
base: /pl/
locale: pl_PL.UTF-8
flag: pl
fallbackType: fallback
fallbacks: '0'Wenn eine Übersetzung fehlt, entscheidet der fallbackType der Sprache:
- strict zeigt nur Inhalte, die in dieser Sprache vorliegen. Nicht übersetzte Elemente fallen weg. Das ist auch der Standard, wenn nichts eingetragen ist.
- fallback zeigt für fehlende Übersetzungen die Inhalte der Sprachen aus der Liste fallbacks, der Reihe nach von links nach rechts.
- free zeigt nur die Datensätze, die in dieser Sprache selbst angelegt sind, unabhängig vom Original.
Für Englisch wählt Mara strict, denn halb deutsche Seiten wären für internationale Studierende verwirrend. Polnisch steht auf fallback mit der 0: Fehlt ein polnischer Text, sehen die Familien den deutschen.
Seiten und Inhalte übersetzen
Bevor die Redaktion Inhalte übersetzen kann, braucht die Seite selbst eine Übersetzung. Erst dann gibt es eine polnische Fassung der Seite, auf der polnische Inhaltselemente stehen können. Einen eigenen Seitenbaum je Sprache braucht man dafür nicht.
Im Bereich „Content“ hat das Modul „Layout“ zwei Ansichten:
- Die Spaltenansicht, im Backend „Layout“ genannt, zeigt die Spalten des Backend-Layouts in einer gewählten Sprache.
- Die Sprachansicht, im Backend „Language Comparison“, stellt die Sprachen nebeneinander. So vergleichst du Original und Übersetzung. Seit TYPO3 14 kannst du dort mehrere Sprachen gleichzeitig auswählen.
Der Übersetzungsassistent. Seit TYPO3 14 öffnet sich in allen Backend-Modulen derselbe schrittweise Assistent, sobald jemand etwas übersetzt. Er bietet zwei Modi an:
- Translate erzeugt eine verbundene Übersetzung, die an ihrem Original hängt.
- Copy erzeugt eine unabhängige Kopie im freien Modus.
Eine automatische Übersetzung per KI gehört nicht zum Assistenten.
Andere Datensätze wie News, Kurse oder Kategorien übersetzt die Redaktion im Modul „Records“. Über die Sprachauswahl blendet sie dort eine oder mehrere Sprachen ein und sieht Original und Übersetzungen zusammen.
Dateien. Bei den Fotos der Lehrkräfte übersetzt man nicht die Bilddateien, sondern ihre Metadaten, also Titel, Beschreibung und Alternativtext. Diese Datensätze liegen in der Tabelle sys_file_metadata. Im Modul „Media“ öffnest du die Metadaten einer Datei und legst eine Übersetzung an. Die Datei selbst bleibt für alle Sprachen dieselbe, niemand lädt sie je Sprache neu hoch. Ein Inhaltselement übernimmt die übersetzten Metadaten. An der Dateireferenz im Inhaltselement kann man Titel und Alternativtext aber auch je Sprache überschreiben.
Den Überblick behalten. Welche Seiten in welche Sprachen übersetzt sind, zeigt die Localization Overview im Bereich „Content“ im Modul „Status“. Dort siehst du den Seitenbaum mit allen Sprachen und legst auch für viele Seiten auf einmal Übersetzungen an.
Suchen im Seitenbaum. Ein Lehrer kennt nur den polnischen Titel einer Seite. Das Suchfeld über dem Seitenbaum findet sie trotzdem, denn es sucht seit TYPO3 14.1 auch in übersetzten Seitentiteln. Das regelt die User-TSconfig-Option options.pageTree.searchInTranslatedPages, deren Standard 1 ist. Mit 0 schaltest du es für einzelne Benutzer oder Gruppen ab. Jeder Benutzer kann die Suche außerdem im Menü des Seitenbaums umschalten.
Verbunden, frei und gemischt
Verbundener Modus. Jede Übersetzung hängt an ihrem Original. Sie übernimmt dessen Reihenfolge und Spalte. Schiebt eine Redakteurin ein deutsches Element nach oben, folgen die englischen und polnischen Übersetzungen der neuen Reihenfolge. Ändert sich das Original, erkennt man die Übersetzung als veraltet und zieht sie nach.
Freier Modus. Die Elemente der Sprache sind unabhängig vom Original. Jede Sprache pflegt ihre eigene Struktur, mit eigenen Elementen und eigener Reihenfolge. Das passt, wenn eine Sprachfassung bewusst anders aufgebaut sein soll, und es passt zum fallbackType free.
Gemischter Modus. Stehen in einer Sprache einer Seite verbundene und frei angelegte Elemente nebeneinander, zeigt das Modul „Layout“ den Hinweis „Mixed Mode“. Das entsteht etwa, wenn jemand verbundene Übersetzungen durch frei angelegte Elemente ergänzt. Dann wird die Pflege schwierig: Beim Umsortieren folgen nur die verbundenen Elemente dem Original, die freien bleiben stehen. Den Übersetzungsassistenten bietet das Modul für diese Sprache nicht mehr an.
Wie wird man den gemischten Modus los? Cache leeren hilft nicht, denn der Zustand steht in den Datensätzen. Entscheide dich für einen Modus. Entferne die Elemente, die nicht dazu passen, und übersetze fehlende Inhalte in diesem Modus neu. TYPO3 wandelt nichts von selbst um.
Sprachpakete für das Backend
Die Backend-Oberfläche hat eigene Sprachen, unabhängig von den Sprachen der Website. Ein Backend auf Polnisch braucht die Übersetzungen des Core und der Extensions. Sie kommen als Sprachpakete.
Im Bereich „System“ öffnest du das Modul „Maintenance“ und dort „Manage Language Packs“. Hier wählst du Sprachen aus und lädst ihre Übersetzungen herunter oder aktualisierst sie. Danach stellt jeder Benutzer seine Backend-Sprache in seinen Einstellungen ein.
Auf der Kommandozeile, etwa bei einem Deployment, erledigt das ein Befehl:
vendor/bin/typo3 language:updateEr lädt die Übersetzungen aller aktiven Extensions für die ausgewählten Sprachen. In einem Composer-Projekt landen die Dateien in var/labels. Seit TYPO3 14.2 gehört der Befehl zum Core und funktioniert auch ohne die Extension install.
Beschriftungen in XLIFF-Dateien
XLIFF steht für XML Localisation Interchange File Format. Es ist ein XML-Format, das Texte mit einer Kennung und ihren Übersetzungen speichert. TYPO3 nutzt es für alle festen Beschriftungen im Backend und im Frontend.
Mara legt die Sprachdateien des Sitepackages in den Ordner Resources/Private/Language. Die Grunddatei heißt locallang.xlf und ist immer auf Englisch, auch wenn die Website auf Deutsch startet. Übersetzungen liegen daneben, mit dem Sprachcode vorne: de.locallang.xlf für Deutsch und pl.locallang.xlf für Polnisch. Fehlt eine Kennung in einer Datei wie de_CH.locallang.xlf, sucht TYPO3 in de.locallang.xlf und zuletzt in der englischen Grunddatei.
Zwei Versionen. Seit TYPO3 14 liest TYPO3 XLIFF 1.2 und XLIFF 2.x. Beide Formate funktionieren nebeneinander, auch im selben Projekt. Bestehende 1.2-Dateien muss niemand umstellen.
- In XLIFF 1.2 steht jeder Eintrag in einem Element trans-unit mit einer id. Darin steht der englische Text in source und die Übersetzung in target.
- In XLIFF 2.0 heißt der Eintrag unit. Darin steckt ein segment mit source und target.
Welche Version eine Datei hat, erkennt der Loader selbst: am Namespace urn:oasis:names:tc:xliff:document:2.0 oder am Attribut version im Wurzelelement. Eine Einstellung, eine eigene Dateiendung oder ein besonderer Ordner sind nicht nötig.
<?xml version="1.0" encoding="UTF-8"?>
<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en" trgLang="pl">
<file id="f1">
<unit id="course.register">
<segment state="final">
<source>Register for a course</source>
<target>Zapisz się na kurs</target>
</segment>
</unit>
</file>
</xliff>Freigegeben oder nicht. TYPO3 nutzt standardmäßig nur freigegebene Übersetzungen. Dafür sorgt die Einstellung requireApprovedLocalizations, die auf true steht. Seit TYPO3 14 liegt sie im Bereich LANG der Systemkonfiguration, früher unter SYS und lang.
- In XLIFF 1.2 trägt ein Eintrag dafür das Attribut approved. Mit dem Wert no wird die Übersetzung übersprungen.
- In XLIFF 2.0 steht der Status im Attribut state am segment. Die Werte heißen initial, translated, reviewed und final. Nur reviewed und final gelten als freigegeben.
- Fehlt das Attribut ganz, gilt die Übersetzung als freigegeben.
Übersetzungsdomänen und Overrides
Bis TYPO3 13 sprach man ein Label nur über einen langen Pfad an. So sieht das aus.
LLL:EXT:lindenau_site/Resources/Private/Language/locallang.xlf:course.registerSeit TYPO3 14 gibt es dafür Übersetzungsdomänen. Das Format lautet Paket, Punkt, Ressource, Doppelpunkt, Kennung. Das Paket ist der Extension-Key. Die Ressource ist der Dateiname ohne Endung und ohne das alte Präfix „locallang_“. Für die Datei locallang.xlf steht das Wort messages. Aus dem langen Pfad wird so lindenau_site.messages:course.register.
backend.toolbar:savemeint die Kennung save in der Dateilocallang_toolbar.xlfder Extension backend.- Die Domänen funktionieren in PHP und in Fluid. Registrieren muss man sie nirgends, TYPO3 findet die Dateien selbst.
- Die alte Schreibweise mit LLL und EXT bleibt gültig.
Beschriftungen eines Plugins überschreiben. Der Elternbereich der Musikschule nutzt das Login-Plugin felogin. Mara gefällt die Überschrift über dem Anmeldeformular nicht. Sie überschreibt sie im TypoScript des Plugins mit _LOCAL_LANG, je Sprache und Kennung:
plugin.tx_felogin_login._LOCAL_LANG {
de.welcome_header = Anmeldung für Eltern
pl.welcome_header = Logowanie dla rodziców
}Labels im ganzen Projekt überschreiben. Für Beschriftungen des Core oder fremder Extensions, etwa im Backend, nutzt Mara die Einstellung resourceOverrides im Bereich LANG der Systemkonfiguration. Sie verweist auf eine eigene XLIFF-Datei im Sitepackage. Deren Kennungen ersetzen die des Originals, die übrigen Labels bleiben erhalten. Früher hieß diese Einstellung locallangXMLOverride und lag unter SYS.
$GLOBALS['TYPO3_CONF_VARS']['LANG']['resourceOverrides']['de']
['EXT:frontend/Resources/Private/Language/locallang_tca.xlf'][]
= 'EXT:lindenau_site/Resources/Private/Language/Overrides/de.locallang_tca.xlf';Der ViewHelper f:translate
Im Fluid-Template gibt f:translate eine Beschriftung aus XLIFF in der aktuellen Sprache aus. Der ViewHelper übersetzt keine Seiteninhalte und wechselt keine Sprache. Inhalte der Redaktion übersetzt man im Backend.
Wie findet er die Datei? Das hängt davon ab, was du angibst:
- Im Extbase-Kontext reicht das Argument key. Dann sucht der ViewHelper in der
locallang.xlfder aktuellen Extension. - Außerhalb von Extbase, etwa in einem Seitentemplate mit PAGEVIEW, ergänzt du key um domain oder extensionName. Sind beide gesetzt, hat domain Vorrang.
- Die Kennung kann die Domäne auch selbst enthalten, etwa
lindenau_site.messages:course.register. - Eine volle Angabe mit LLL und EXT funktioniert überall, auch außerhalb von Extbase.
Ein typischer Fehler. Mara schreibt im Seitentemplate nur ein f:translate mit key form.legend, und die Seite bricht mit einer Exception ab. Ohne Extbase-Kontext kann der ViewHelper die Extension nicht ableiten. Die Lösung ist domain mit dem Wert lindenau_site, extensionName oder eine volle LLL-Angabe.
default legt einen Ersatztext fest, der erscheint, wenn die Kennung in der Sprachdatei fehlt. Als Lösung für die Exception taugt er nicht: Er verdeckt den Fehler, und es erscheint immer nur der Ersatztext.
Werte einsetzen. Enthält ein Label Platzhalter wie %s oder %d, übergibst du die Werte mit dem Argument arguments. Sie ersetzen die Platzhalter in ihrer Reihenfolge. Nummerierte Platzhalter greifen gezielt auf einen Wert zu. So kann eine Übersetzung die Reihenfolge im Satz ändern, ohne dass sich der Aufruf ändert.
<!-- Label: "%2$s hat noch %1$d freie Plätze" -->
<f:translate key="course.seats" domain="lindenau_site"
arguments="{0: course.freeSeats, 1: course.title}" />Plural und Geschlecht mit ICU. Seit TYPO3 14.2 versteht TYPO3 das ICU MessageFormat. Damit formulierst du Pluralformen, Auswahlen mit select, etwa nach Geschlecht, und benannte Platzhalter. Die Erkennung ist automatisch: Übergibst du benannte Argumente, also ein assoziatives Array, und enthält das Label ein ICU-Muster, kommt der ICU MessageFormatter zum Einsatz. Mit nummerierten Werten und %s bleibt es bei der alten Ersetzung, geschweifte Klammern allein schalten ICU nicht ein. Das gilt für XLIFF 1.2 und 2.x, im Frontend wie im Backend.
<!-- Label: {count, plural, =0 {Keine freien Plätze} one {Ein freier Platz} other {# freie Plätze}} -->
<f:translate key="free_seats" domain="lindenau_site" arguments="{count: course.freeSeats}" />Sprache vorgeben. In einer FluidEmail, die ein Scheduler-Task oder ein Konsolenbefehl verschickt, gibt es keine Frontend- oder Backend-Anfrage. Der ViewHelper weiß dann nicht, welche Sprache gilt. Mit languageKey, etwa pl, legst du sie ausdrücklich fest.
Als Wert eines Attributs. Ein Tag kann nicht innerhalb eines Attributs stehen. Für den Alternativtext eines Bildes nutzt du deshalb die Inline-Schreibweise:
<f:image image="{teacher.photo}" alt="{f:translate(key: 'image.alt', domain: 'lindenau_site')}" />Der Sprachumschalter
Oben rechts auf der Website soll ein Sprachumschalter stehen. Die Daten dafür liefert der LanguageMenuProcessor, kurz language-menu. Er liest die Sprachen aus der Site-Konfiguration und gibt sie über dataProcessing an das Fluid-Template. Das geht mit PAGEVIEW genauso wie mit FLUIDTEMPLATE.
page.10 = PAGEVIEW
page.10 {
paths.10 = EXT:lindenau_site/Resources/Private/PageView/
dataProcessing.20 = language-menu
dataProcessing.20 {
languages = auto
as = languageNavigation
addQueryString.exclude = utm_source,utm_medium
}
}- languages steht auf auto, dann nimmt der Processor alle Sprachen der Site. Alternativ gibst du eine Liste von Sprach-IDs an, etwa 0,1,2.
- as legt den Namen der Variablen im Template fest. Ohne Angabe heißt sie languagemenu.
- addQueryString.exclude nennt Parameter, die in den Sprachlinks wegfallen sollen. Der Processor übernimmt nämlich die aktuellen Parameter der URL in jeden Sprachlink, bei der Musikschule auch Tracking-Parameter aus dem Newsletter.
Jeder Menüpunkt bringt unter anderem diese Angaben mit: link, hreflang, navigationTitle, title, active und available. Wer eine Übersetzung angelegt hat oder wann, liefert der Processor nicht. Das hreflang kommt direkt aus der Site-Konfiguration und ist für Suchmaschinen wichtig.
Zwei Angaben werden gern verwechselt:
- active markiert die Sprache, die der Besucher gerade sieht.
- available sagt, ob es die aktuelle Seite in dieser Sprache gibt.
<f:for each="{languageNavigation}" as="item">
<f:if condition="{item.available}">
<f:then>
<a href="{item.link}" hreflang="{item.hreflang}" class="{f:if(condition: item.active, then: 'active')}">{item.navigationTitle}</a>
</f:then>
<f:else>
<span>{item.navigationTitle}</span>
</f:else>
</f:if>
</f:for>Der Processor erkennt nicht die Sprache des Browsers und leitet Besucher auch nicht weiter. Er liefert nur die Daten für das Menü.
Zeichensätze und UTF-8
Polnisch bringt Zeichen wie ł, ż und ę mit. Sie kommen nur richtig an, wenn die Kodierung stimmt.
Ein Zeichensatz, englisch Charset, legt fest, welche Zeichen es gibt und welche Zahlenwerte sie haben. Die Kodierung bestimmt, wie diese Zahlen als Bytes gespeichert werden. Mit der Schriftart hat das nichts zu tun, sie bestimmt nur das Aussehen.
- ASCII nutzt 7 Bit und kennt 128 Zeichen: englische Buchstaben, Ziffern und Satzzeichen, aber keine Umlaute.
- ISO-8859-1, auch Latin-1, nutzt ein Byte je Zeichen und kennt 256 Zeichen, vor allem westeuropäische. Das ä ist dabei, das polnische ł nicht.
- UTF-8 deckt den ganzen Unicode-Bereich ab, also alle Schriften. Es ist heute der Standard im Web, und TYPO3 arbeitet durchgehend damit.
UTF-8 braucht 1 bis 4 Bytes je Zeichen. ASCII-Zeichen brauchen ein Byte und sind byte-gleich mit ASCII. Ein ASCII-Text ist also schon gültiges UTF-8.
Umlaute brauchen 2 Bytes, viele Schriftzeichen wie Chinesisch 3, Emojis 4. Daraus folgen zwei typische Fehler:
- Zeichensalat beim Import. Eine alte CSV-Datei mit Kursdaten zeigt Umlaute als ä. Das ä besteht in UTF-8 aus zwei Bytes. Liest ein Programm sie als ISO-8859-1, entstehen zwei einzelne Zeichen. Ursache ist eine falsch gelesene Kodierung, nicht die Schriftart. Beide Seiten müssen dieselbe Kodierung verwenden.
- Verlorene Emojis in MySQL. Der alte MySQL-Zeichensatz utf8, genauer utf8mb3, speichert höchstens 3 Bytes je Zeichen. Emojis brauchen aber 4 Bytes und gehen verloren. Für den ganzen Unicode-Bereich braucht die Datenbank utf8mb4.
Das Wichtigste in Kürze
- Sprachen stehen in der Site-Konfiguration, das Locale muss auf dem Server installiert sein.
- strict zeigt nur Übersetztes, fallback füllt aus der Liste fallbacks auf, free zeigt nur Datensätze der Sprache selbst.
- Erst die Seite übersetzen, dann die Inhalte. Translate erzeugt verbundene Übersetzungen, Copy freie Kopien.
- Verbundene Übersetzungen folgen Reihenfolge und Spalte des Originals. Den gemischten Modus bereinigt man auf einen Modus.
- Sprachpakete kommen über „Manage Language Packs“ oder den Befehl language:update nach
var/labels. - XLIFF 1.2 nutzt trans-unit, XLIFF 2.0 unit und segment. TYPO3 14 erkennt die Version selbst.
- Ohne Freigabe wird eine Übersetzung übersprungen, solange
requireApprovedLocalizationsaktiv ist. - Übersetzungsdomänen kürzen Pfade: messages steht für
locallang.xlf. - Plugins überschreibt man mit
_LOCAL_LANG, ganze Projekte mitresourceOverridesim Bereich LANG. f:translatebraucht außerhalb von Extbase domain, extensionName oder eine volle LLL-Angabe.- Im Sprachumschalter prüft man active und available.
- UTF-8 braucht 1 bis 4 Bytes je Zeichen, MySQL dafür utf8mb4.
Begriffe
- Fallback-Kette
- Liste von Ersatzsprachen, die TYPO3 der Reihe nach durchsucht, wenn eine Übersetzung fehlt.
- Freier Modus
- Übersetzungen als unabhängige Elemente mit eigener Struktur.
- Gemischter Modus
- Verbundene und freie Elemente in derselben Sprache einer Seite.
- ICU MessageFormat
- Standard für Labels mit Pluralformen, Auswahlen und benannten Platzhaltern.
- Locale
- Einstellung für Sprache und Region, steuert etwa Datums- und Zahlenformate.
- Sprachpaket
- Übersetzungen des Core und der Extensions für die Backend-Oberfläche.
- Übersetzungsdomäne
- Kurzname für eine Sprachdatei aus Paket und Ressource, etwa lindenau_site.messages.
- UTF-8
- Kodierung für ganz Unicode mit 1 bis 4 Bytes je Zeichen.
- Verbundener Modus
- Übersetzungen, die an ihrem Original hängen und ihm folgen.
- XLIFF
- XML-Format für Sprachdateien mit Kennungen und Übersetzungen.