> ## Documentation Index > Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt > Use this file to discover all available pages before exploring further. # Textbausteine > Textbausteine sind der zentrale Ort, an dem alle Texte gepflegt werden, die der Shop an verschiedenen Stellen anzeigt. export const confRechte = "Einstellungen -> Benutzer -> Benutzer bearbeiten"; export const confTextbausteine = "Templates und Content -> Textbausteine und Übersetzungen"; Ein Textbaustein besteht aus einer Bezeichnung und einem Text. Im Template wird nur die Bezeichnung eingebunden, nicht der Text selbst. Dadurch wird der Text an einer Stelle geändert und die Änderung wirkt sich überall dort aus, wo der Baustein vorkommt. Typische Beispiele hierfür sind Buttons, Hinweise, Fehlermeldungen und rechtliche Texte. | Bezeichnung | Text (Deutsch) | Text (Englisch) | | -------------------------------------- | -------------------------- | ----------------------- | | `shop.basket.addButton` | In den Warenkorb | Add to cart | | `shop.checkout.shippingNote` | Versandkostenfrei ab 50 €. | Free shipping from €50. | | `ws.error.addressValidation.minLength` | Die Eingabe ist zu kurz. | The entry is too short. | Die Bezeichnung ist der technische Name, unter dem das Template oder eine Konfiguration den Text anfordert. Der Text ist das, was der Kunde im Shop liest. ## Sprachen sind die Grundlage Textbausteine existieren immer im Zusammenhang mit einer Sprache. Drei Punkte gehören dafür zusammen: * **Jede Sprache wird einmal im Shop angelegt** – als eigenständiges Objekt in der Konfiguration, nicht im Textbaustein-Dienst. * **Jeder Subshop hat genau eine Sprache.** Welcher Text ein Kunde sieht, hängt davon ab, welchen Subshop er aufruft: Der Subshop bestimmt die Sprache, die Sprache bestimmt den Text. * **Ein Textbaustein hat je Sprache eine eigene Fassung.** Die Bezeichnung ist immer dieselbe, der Text unterscheidet sich. Solange keine Sprache angelegt und keinem Subshop zugewiesen ist, gibt es auch keine Texte, die der Shop ausgeben könnte. Wie Sprachen angelegt, zugewiesen und miteinander verkettet werden, steht unter [Sprachen anlegen und zuweisen](#sprachen-anlegen-und-zuweisen). ## Textpflege Gepflegt werden die Texte im Admin Interface unter dem Dienst {confTextbausteine}, erreichbar unter: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/text ``` Die Rechte werden je Dienst vergeben, unter {confRechte}. Für die Textbausteine gibt es fünf davon: | Recht | Erlaubt | | --------------- | --------------------------------------------------------------------- | | **Ansehen** | Die Übersicht öffnen, Texte ansehen, suchen und filtern, exportieren. | | **Bearbeiten** | Bestehende Texte ändern. | | **Erstellen** | Neue Textbausteine anlegen und bestehende duplizieren. | | **Löschen** | Textbausteine oder einzelne Sprachen eines Textbausteins entfernen. | | **Publizieren** | Änderungen im Shop wirksam machen. | | **Alle** | Alle genannten Rechte sind vergeben. | Ein Import benötigt beispielsweise die Rechte Anlegen und Bearbeiten. Die Rechte gelten immer für den ganzen Dienst, nicht für einzelne Sprachen. Wer Texte lesen darf, sieht alle Sprachen; wer bearbeiten darf, kann alle Sprachen ändern. Eine Beschränkung auf einzelne Sprachen – etwa für externe Übersetzer – ist derzeit nicht möglich. Für einen Übersetzungsauftrag ist deshalb der [Export einer einzelnen Sprache](#import-und-export) der geeignete Weg. ## Die Übersicht Textblocks Lang3 Der Dienst zeigt eine Tabelle, in der jede Zeile einem Textbaustein und jede weitere Spalte einer Sprache entspricht. Bis zu drei Sprachen lassen sich gleichzeitig nebeneinander vergleichen und direkt in der Tabelle bearbeiten. Welche Sprachen als Spalten erscheinen, wählen Sie selbst; per Drag & Drop lassen sie sich umsortieren. Die linke Sprachspalte ist die Fokussprache. Sie ist hervorgehoben, und die Verfügbarkeitsfilter beziehen sich immer auf sie – nicht auf die anderen sichtbaren Spalten. Eine Sprache nach ganz links zu ziehen, macht sie zur Fokussprache. ### Der Verfügbarkeitsstatus Der Verfügbarkeitsstatus gibt Auskunft über den Status eines Textbausteins in einer bestimmten Sprache. Es gibt drei Ausprägungen, die in den Zellen farblich hinterlegt sind: * **grün = gepflegt** – es liegt ein Text vor. * **gelb = leer** – es gibt zwar einen Eintrag für diese Sprache, aber ohne Inhalt. * **rot = nicht vorhanden** – für diese Sprache existiert noch gar kein Eintrag. So lässt sich auf einen Blick erkennen, wo in einer Sprache noch Lücken bestehen. ### Suchen und Filtern Da mit der Zeit viele Textbausteine über mehrere Sprachen hinweg entstehen, lässt sich die Übersicht durchsuchen und filtern. * **Suche** – über Bezeichnung und Text. * **Verfügbarkeit** – genau die drei Farben aus der Tabelle. Sie können also gezielt alle Bausteine anzeigen, die in der Fokussprache leer oder nicht vorhanden sind, und so die Lücken einer Sprache abarbeiten. Mehrere Zustände lassen sich kombinieren; angezeigt wird dann, was einen der gewählten Zustände hat. * **Typ** – System-Textbausteine oder eigene Textbausteine. * **Verwendung** – ob der Baustein in einem Template referenziert wird. Der Bezug lässt sich auf einen einzelnen Subshop einschränken, weil die Templates verschiedener Subshops unterschiedliche Bausteine nutzen können. Wie dieser Stand entsteht, steht unter [Wirkung im Shop](#wirkung-im-shop). * **Namensraum** – eine Baumansicht über die Punkt-Ebenen der Bezeichnungen. Der Baum ist nicht vorgegeben, sondern entsteht aus den Bezeichnungen, die tatsächlich im Shop existieren: Aus `shop.checkout.button.label` werden die Ebenen `shop`, `shop.checkout` und `shop.checkout.button`. Wie brauchbar dieser Filter ist, hängt also davon ab, wie konsequent die Bezeichnungen benannt sind. Wer neue Bausteine nach einem festen Schema benennt – etwa mit einem Präfix je Shop-Bereich –, kann später gezielt einen Bereich herausfiltern. ## System- und eigene Textbausteine ### System-Textbausteine System-Textbausteine werden vom Shop **automatisch erzeugt**. Sie entstehen aus Konfigurationsfeldern, die vom System vorgegeben und nicht editierbar sind – in aller Regel Fehlertexte. Ihre Bezeichnung beginnt mit `ws.error.` Solche Felder gibt es nicht nur bei den [actions](/konfiguration/actions-fehlertexte-e-mails), sondern auch in anderen Bereichen wie Checkout, Benutzerkonten und externen Datenquellen. Das Feld in der Konfiguration trägt dabei nicht den Fehlertext, sondern nur die Bezeichnung des Textbausteins; gepflegt wird der Text ausschließlich hier im Textbaustein-Dienst. Bei Shop-Updates kommen laufend neue System-Textbausteine dazu, sobald neue Konfigurationsbereiche oder Erweiterungen ausgeliefert werden. Diese werden in der Regel mit deutschem Text ausgeliefert, und zwar nur in der Hauptsprache des jeweiligen Subshops. Texte für weitere Sprachen müssen Sie selbst hinterlegen. Nach einem Update lohnt sich deshalb ein Blick auf den Verfügbarkeitsfilter: Fokussprache auf die betreffende Sprache setzen und nach *nicht vorhanden* filtern zeigt genau die neu dazugekommenen Lücken. Was Sie mit System-Textbausteinen tun dürfen und was nicht: * **Der Text ist frei änderbar** – in jeder Sprache, ohne Einschränkung. Sie können also die Formulierung einer Fehlermeldung vollständig an Ihr Wording anpassen. * **Die Bezeichnung ist gesperrt.** System-Textbausteine lassen sich weder umbenennen noch löschen – auch nicht sprachweise. Der Shop verweist an fester Stelle auf diese Bezeichnung; ohne sie stünde dort kein Text. ### Eigene Textbausteine Bei der Bereitstellung eines Shops wird bereits ein großer Satz eigener, frei änderbarer Textbausteine ausgeliefert. Die Templates selbst enthalten **keine** Texte – sämtliche Texte liegen in Textbausteinen. Dadurch lässt sich das gesamte Wording eines Shops über diesen Dienst anpassen, ohne ein Template zu berühren. Darüber hinaus können Sie beliebig viele eigene Textbausteine anlegen, etwa für individuelle Hinweise oder Inhalte, die nur in diesem Shop gebraucht werden. Diese lassen sich vollständig anlegen, bearbeiten, umbenennen und wieder löschen. **Erlaubte Zeichen in der Bezeichnung:** Buchstaben `a–z` und `A–Z`, Ziffern `0–9`, Punkt `.` und Unterstrich `_`. Nicht erlaubt sind Leerzeichen, Bindestriche, Umlaute und alle übrigen Sonderzeichen. Der Punkt ist dabei mehr als ein Trennzeichen: Er bildet die Ebenen des Namensraum-Filters (siehe [Suchen und Filtern](#suchen-und-filtern)). Das Präfix `ws.` ist für System-Textbausteine reserviert und lässt sich nicht vergeben. Einen Textbaustein anzulegen genügt nicht, damit er im Shop erscheint. Die Bezeichnung muss zusätzlich an der gewünschten Stelle im Template oder in einer Konfiguration eingesetzt werden. Umgekehrt gilt beim Löschen dasselbe: Entfernen Sie den Baustein erst aus Template und Konfiguration und löschen Sie ihn danach – sonst verweist die Ausgabestelle auf eine Bezeichnung, die es nicht mehr gibt. Wie ein Textbaustein im Template eingebunden wird, steht unter [Template Engine](/frontend/die-basics/template-engine). ### Textbausteine in Konfigurationen Nicht nur Templates verweisen auf Textbausteine, sondern auch Konfigurationen. Überall dort, wo eine Konfiguration einen Text enthält, der im Frontend erscheint, kann statt eines festen Werts die Bezeichnung eines Textbausteins stehen. Das ist nicht auf System-Textbausteine beschränkt – Sie können dort auch eigene Bausteine referenzieren. Der Vorteil: Dieselbe Konfiguration lässt sich in mehreren Sprachversionen eines Shops verwenden, ohne sie je Sprache zu duplizieren. Einzelheiten unter [Verwendung von Textbausteinen in Konfigurationen](/konfiguration#verwendung-von-textbausteinen-in-konfigurationen). Ein Textbaustein, auf den eine Konfiguration verweist, lässt sich nicht löschen, solange der Verweis besteht. Entfernen Sie zuerst den Verweis in der Konfiguration. ### Nicht verwendete Bausteine aufräumen Der Filter **nicht verwendet** zeigt Textbausteine, die in keinem Template mehr vorkommen. Das ist mehr als Kosmetik. Nach einem Relaunch, einem Template-Umbau oder größeren Änderungen am Shop bleiben regelmäßig Bausteine zurück, die niemand mehr braucht. Solange sie in der Liste stehen, tauchen sie bei jeder neuen Sprache wieder auf – und werden mitübersetzt. Wer vor dem Hinzufügen eines neuen Subshops oder einer neuen Sprache einmal nach nicht verwendeten Bausteinen filtert und aufräumt, spart genau diesen Aufwand. Es werden dann nur noch die Texte angezeigt und übersetzt, die der Shop tatsächlich ausgibt. Prüfen Sie vor dem Löschen, ob der Stand aktuell ist: Die Verwendung wird bei der Template-Kompilierung ermittelt (siehe [Wirkung im Shop](#wirkung-im-shop)). Direkt nach einer Template-Änderung ohne erneutes Veröffentlichen ist die Anzeige noch nicht auf dem neuesten Stand. ## Sprachen anlegen und zuweisen Dieser Abschnitt betrifft die Shop-Administration. Für die tägliche Redaktionsarbeit wird er nicht gebraucht – er erklärt, wie die Sprachen entstehen, mit denen der Textbaustein-Dienst arbeitet. Sprachen werden nicht im Textbaustein-Dienst gepflegt, sondern in der Shop-Konfiguration. Drei Schritte gehören dazu, und ihre Reihenfolge erklärt zugleich, wie die Vererbung funktioniert. ### 1. Die Sprache anlegen Jede Sprache ist ein eigener Konfigurationsknoten unter `general.language` mit einem Namen und einem ISO-Code. Referenz und Parameter: [`general` – Allgemeine Shopeinstellungen](/konfiguration/general-allgemeine-shopeinstellungen). ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https:///admin/config/general.language ``` Sobald eine Sprache existiert, erscheint sie im Textbaustein-Dienst als wählbare Spalte – zunächst überall rot, weil noch kein Text gepflegt ist. ### 2. Die Sprache einem Subshop zuweisen Ein Subshop bekommt **genau eine** Sprache. Sie wird an zwei Stellen hinterlegt, und beide müssen dieselbe Sprache nennen: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https:///admin/config/general.subshopView https:///admin/config/general.subshop ``` Am häufigsten übersehen wird, dass es zwei Stellen sind. Wird nur eine geändert, bleibt der Fehler unauffällig, weil der Shop weiterhin Texte anzeigt – nur die falschen. Ein österreichischer Subshop erscheint dann etwa weiterhin mit deutschen Texten, obwohl österreichische Sprachvarianten gepflegt sind. Prüfen Sie in diesem Fall zuerst, ob `general.subshopView` und `general.subshop` dieselbe Sprache nennen. ### 3. Ersatzsprachen hinterlegen Textblocks Languagechains Damit nicht jede Sprachvariante vollständig gepflegt werden muss, kann eine Sprache eine geordnete Reihe von **Ersatzsprachen** besitzen. Fehlt ein Text in der eigentlichen Sprache oder ist er leer, greift die nächste Sprache dieser Reihe. Wichtig ist, wo diese Reihe hinterlegt wird: **Sie gehört zur Sprache, nicht zum Subshop.** Der Subshop bringt nur seine eine Sprache mit; welche Ersatzsprachen dahinter stehen, entscheidet die Sprache selbst. Daraus ergibt sich die wirksame Reihenfolge: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} Sprache des Subshops → deren Ersatzsprache 1 → deren Ersatzsprache 2 → … ``` Ein Beispiel für einen österreichischen Subshop: 1. Der Subshop bekommt die Sprache **Deutsch (AT)**. 2. Bei der Sprache **Deutsch (AT)** wird **Deutsch** als Ersatzsprache eingetragen. 3. Ergebnis: Fehlt ein Text auf Deutsch (AT), zeigt der Shop den deutschen Text. Die Kette zeigt also immer von der **spezielleren** Sprache zur allgemeineren. Wer von WEBSALE V8s kommt, erwartet häufig das umgekehrte Muster: eine Mastersprache `DEU`, bei der die Varianten `AT` und `CH` als Ersatzsprachen hinterlegt werden. Das führt nicht zum Ziel und ist die häufigste Ursache dafür, dass ein Subshop trotz gepflegter Sprachvariante die Texte der Basissprache zeigt. Richtig ist umgekehrt: `AT` und `CH` sind eigene Sprachen, und bei **jeder** von ihnen wird `DEU` als Ersatzsprache eingetragen. Ketten können mehrstufig sein – etwa eine sehr spezielle Variante, die zunächst auf eine allgemeinere und erst danach auf die Basissprache zurückfällt. Dabei gilt: **Die Kette wird nicht weitervererbt.** Jede Sprache trägt ihre vollständige Reihe selbst. Damit `de-at-b2b` über `de-at` bis `de` durchfällt, müssen bei `de-at-b2b` beide eingetragen sein. Es genügt nicht, dass `de-at` seinerseits auf `de` verweist. Der Effekt für die Redaktion: Es ist nicht nötig, jeden Text in jeder Sprachvariante zu pflegen. Es reicht, die Basissprache vollständig zu pflegen. Speziellere Varianten übernehmen deren Inhalte automatisch, solange sie keinen eigenen Text haben. Erst wenn eine Variante einen abweichenden Text braucht, tragen Sie ihn dort gezielt ein – er überschreibt dann nur für diese Sprache die geerbte Fassung. Für die Ausgabe im Shop verhalten sich **leer** und **nicht vorhanden** gleich: Beide lösen den Rückgriff auf die Ersatzsprache aus. Ein bewusst leer gespeicherter Text unterdrückt die Ausgabe also nicht – solange eine Sprache der Kette einen Text enthält, wird dieser angezeigt. Um an einer Stelle wirklich nichts anzuzeigen, muss der Text in allen Sprachen der Kette leer oder nicht vorhanden sein. Der Unterschied zwischen den beiden Zuständen ist damit vor allem ein Merkmal für die Redaktion: Er zeigt, ob eine Sprache bereits bearbeitet wurde. ## Wirkung im Shop Zwei Punkte sind für das Verständnis zentral, weil sie leicht zu Verwirrung führen: Ein Textbaustein wird nur angezeigt, wenn er an der passenden Stelle im Template eingebunden ist. Das Anlegen oder Ändern eines Textbausteins allein reicht nicht aus. Die jeweilige Shop-Seite muss an der betreffenden Stelle auch tatsächlich auf diesen Textbaustein verweisen. Ändert man einen bereits eingebundenen Textbaustein, wirkt sich das direkt aus. Ein komplett neuer Textbaustein erscheint im Frontend erst, sobald er zusätzlich ins jeweilige Template eingefügt wurde. Bis zur Veröffentlichung befinden sich Anpassungen im Bearbeitungsstand, ohne dass Kunden sie bereits sehen. Beim Veröffentlichen werden die Templates mit den zuletzt geänderten Texten neu kompiliert – derselbe Vorgang, der auch den Verwendungs-Stand neu berechnet. Daraus folgt für den Filter **Verwendung**: Er spiegelt den Stand der letzten Kompilierung wider, nicht den aktuellen Template-Inhalt. Nach Änderungen an Templates ist er erst nach erneutem Veröffentlichen aktuell. Eine reine Textänderung ohne Template-Änderung verändert die Verwendung nicht. ## Import und Export Textblocks Export Größere Mengen an Textbausteinen lassen sich exportieren und wieder importieren, beispielsweise um sie extern übersetzen zu lassen oder um Änderungen gesammelt einzuspielen. Dies kann auf eine einzelne Sprache eingeschränkt werden, sodass beispielsweise nur die französischen Texte exportiert, extern übersetzt und anschließend wieder importiert werden. Der Export berücksichtigt die aktuell gesetzte Suche sowie die gesetzten Filter. Beide Vorgänge laufen im Hintergrund und werden durch eine Fortschrittsanzeige begleitet. Importierte Texte werden ebenfalls erst nach der Veröffentlichung im Shop sichtbar. System-Textbausteine lassen sich per Import aktualisieren, aber nicht neu anlegen – das Präfix `ws.` bleibt dem System vorbehalten. Vor größeren oder destruktiven Aktionen empfiehlt sich ein Export als Sicherung, weil sich ein Export unverändert wieder importieren lässt. ## Wegweiser * [Template Engine](/frontend/die-basics/template-engine) – wie Textbausteine im Template eingebunden werden. * [actions – Fehlertexte & E-Mails](/konfiguration/actions-fehlertexte-e-mails) – wie die System-Fehlertexte (`ws.error.*`) aufgebaut sind. * [Übersicht – Konfiguration](/konfiguration#verwendung-von-textbausteinen-in-konfigurationen) – wie Konfigurationen auf Textbausteine verweisen, statt feste Texte zu enthalten. * [`general` – Allgemeine Shopeinstellungen](/konfiguration/general-allgemeine-shopeinstellungen) – Referenz zu `general.language`, `general.subshop` und `general.subshopView`. * [Konfigurations-Deeplinks](/admin-interface/konfigurations-deeplinks) – direkte Links zu den Konfigurationsknoten. * [API-Referenz Textbausteine](/schnittstellen/admin-interface-api/api-referenz-textbausteine) – Endpunkte, Filter und Import-/Export-Schnittstelle. ## Related topics - [Template Engine](/frontend/die-basics/template-engine.md) - [API-Referenz Textbausteine](/schnittstellen/admin-interface-api/api-referenz-textbausteine.md) - [Übersicht - Konfiguration](/konfiguration.md) - [actions - Fehlertexte & E-Mails](/konfiguration/actions-fehlertexte-e-mails.md) - [Changelog](/changelog.md)