Die meisten Anwender werden das Widget oder den Block nutzen, den der Multisite Language Switcher bereitstellt. Aber eine dynamische Seitenleiste ist nicht immer der beste Ort für die Ausgabe des Plugins. Dieser Bereich richtet sich an alle, die den Sprachumschalter in eigene Templates, Blöcke, Plugins oder Add-ons einbauen wollen.
Eine Bitte vorweg: Sichern Sie immer Ihre Dateien und Ihre Datenbank, bevor Sie an Ihrer Website arbeiten. Sicher ist sicher.
Wenn Sie Erklärungen zu den Einstellungen und der täglichen Arbeit mit dem Plugin suchen, dann besuchen Sie bitte die Einführung für Anwender.
Stand dieser Dokumentation
Diese Dokumentation beschreibt Version 3.0 des Plugins. Version 3.0 hat die interne Struktur des Codes deutlich umgebaut und die öffentlichen Funktionen umbenannt. Wenn Sie von 2.x kommen, lesen Sie bitte den Abschnitt „Migration von 2.x nach 3.0″ weiter unten. Ihr bestehender Code läuft weiter, aber nicht mehr ohne Hinweismeldungen.
| Angabe | Wert |
|---|---|
| Aktuelle Version | 3.0.1 |
| Mindestanforderung PHP | 7.4 |
| Voraussetzung | WordPress Multisite |
| Quellcode | github.com/lloc/Multisite-Language-Switcher |
Die englische Referenz im Repository unter docs/ wird zusammen mit dem Code gepflegt und ist bei Abweichungen die maßgebliche Quelle. Diese Seiten sind die deutsche Fassung davon.
Drei Wege zur Ausgabe
Für die Ausgabe des Sprachumschalters gibt es drei Wege, die alle denselben Code verwenden und sich nur im Aufrufkontext unterscheiden.
Im Editor: Der Block „Multisite Language Switcher“ beziehungsweise das klassische Widget. Nichts zu programmieren.
In Inhalten: Der Shortcode \[sc_msls\].
Im Template: Die Funktion msls_the_switcher() gibt den Umschalter direkt aus, msls_get_switcher() liefert ihn als String zurück.
if ( function_exists( 'msls_the_switcher' ) ) {
msls_the_switcher();
}
Der function_exists()-Test ist keine Förmlichkeit: Ohne ihn zerlegt ein deaktiviertes Plugin Ihr Template. Alle Funktionen, die das Plugin öffentlich anbietet, finden Sie auf der Seite API-Funktionen.
Worauf sich Add-ons verlassen können
Ab dem Moment, in dem WordPress die Datei MultisiteLanguageSwitcher.php einbindet, also noch vor plugins_loaded, steht Folgendes bereit, unabhängig davon, in welcher Reihenfolge WordPress die Plugins lädt:
- die
msls_*()-Funktionen ausincludes/api.phpund die überholten Namen ausincludes/deprecated.php - jede Klasse unter
lloc\Msls\über den PSR-4-Autoloader von Composer - jeder flache Klassenname aus der Zeit vor 3.0, etwa
lloc\Msls\MslsOptionsoderlloc\Msls\MslsOutput, alsclass_alias()
Das ist eine bewusste Zusage an Add-ons: Ein class_exists( 'lloc\Msls\MslsOptions' ) zum frühen Zeitpunkt liefert true. In 3.0.0 war dieser Test zeitweise gebrochen, weil Aliase und Funktionen erst auf plugins_loaded geladen wurden. Add-ons wie MslsMenu haben sich daraufhin still selbst deaktiviert. Der Fehler ist behoben und der Ladezeitpunkt ist jetzt Teil des Vertrags.
Die Hooks dagegen greifen erst ab plugins_loaded und später. Registrieren Sie Ihre Callbacks also wie gewohnt aus plugins_loaded, init oder einem noch späteren Zeitpunkt heraus.
Die Paketstruktur seit 3.0
Vor 3.0 lagen alle Klassen flach im Namespace lloc\Msls\ und trugen das Präfix Msls im Namen. Seit 3.0 sind sie nach Zuständigkeit in Unter-Namespaces sortiert:
| Namespace | Inhalt |
|---|---|
lloc\Msls\Admin\ | Einstellungsseite, Metaboxen, Spalten, Filter, Übersetzungs-Auswahl |
lloc\Msls\Blog\ | Blog und Collection: die Blogs des Netzwerks und ihre Sprachen |
lloc\Msls\ContentImport\ | Der Content-Importer samt Importern, Logger und Relationen |
lloc\Msls\ContentTypes\ | Welche Post Types und Taxonomien als übersetzbar gelten |
lloc\Msls\Frontend\ | Ausgabe, Shortcode, Block, Widget, Content-Filter, hreflang |
lloc\Msls\Link\ | Die vier Darstellungsvarianten eines Sprachlinks |
lloc\Msls\Options\ | Einstellungen sowie die Übersetzungsdaten von Posts, Terms und Archiven |
lloc\Msls\Registry\ | Die Singleton- und Registry-Infrastruktur |
lloc\Msls\RestApi\ | Der REST-Endpunkt hinter „Quick Create“ |
lloc\Msls\Compat\ | Die Aliase auf die alten Klassennamen |
Neu geschriebener Code sollte die Namespace-Namen verwenden. Die Aliase existieren für bestehenden Fremdcode, nicht als gleichwertige Alternative.
Zur Orientierung im Code liegen im Repository ein Klassendiagramm und ein Paketdiagramm, die aus dem Quellcode generiert werden.
Neu in 3.0: Quick Create
Das sichtbarste neue Feature von 3.0 ist Quick Create: Eine Übersetzung lässt sich direkt aus der Metabox im Editor anlegen, und über den Menüpunkt „Add from Translation“ auch für einzelne oder mehrere Beiträge auf einmal. Darunter liegt ein REST-Endpunkt, der sich über eine ganze Reihe von Hooks steuern lässt, von der Berechtigungsprüfung (msls_quick_create_capability) über die Daten des neuen Beitrags (msls_quick_create_post_data) bis zur Antwort des Endpunkts (msls_quick_create_response).
Die Details stehen in der Hook-Referenz, ein Beispiel in den Snippets.
Migration von 2.x nach 3.0
Zwei Dinge haben sich geändert, die Ihren bestehenden Code betreffen. Beide sind rückwärtskompatibel, aber nur die Klassennamen sind es geräuschlos.
Die Funktionsnamen
Seit 2.10.1 tragen alle öffentlichen Funktionen ein msls_-Präfix, damit sie den WordPress Coding Standards entsprechen. Die alten Namen funktionieren weiter, geben aber bei jedem Aufruf eine _deprecated_function()-Meldung aus. Bei aktivem WP_DEBUG landet die im Log, und irgendwann fällt sie weg.
| Alt (überholt) | Neu |
|---|---|
get_the_msls( $attr ) | msls_get_switcher( $attr = array() ) |
the_msls( $arr ) | msls_the_switcher( $arr = array() ) |
get_msls_flag_url( $locale ) | msls_get_flag_url( $locale ) |
get_msls_blog_description( $locale, $preset ) | msls_get_blog_description( $locale, $preset ) |
get_msls_permalink( $locale, $preset ) | msls_get_permalink( $locale, $preset ) |
Nebenbei: Bei msls_get_switcher() ist das Argument seit 3.0 optional. get_the_msls() verlangte es zwingend.
Ein Suchen-und-Ersetzen über Ihr Theme und Ihre Plugins genügt in der Regel. Prüfen Sie danach das Debug-Log auf verbliebene Meldungen.
Die Klassennamen
Wenn Sie Klassen des Plugins direkt verwenden, etwa MslsBlogCollection::instance() in einem älteren Snippet, dann läuft dieser Code über die Aliase lloc\Msls\Compat\Aliases unverändert weiter, ohne Meldung. Die Umstellung ist trotzdem sinnvoll, weil neue Klassen nur noch unter den neuen Namen dokumentiert werden.
| Alt | Neu |
|---|---|
lloc\Msls\MslsBlogCollection | lloc\Msls\Blog\Collection |
lloc\Msls\MslsBlog | lloc\Msls\Blog\Blog |
lloc\Msls\MslsOptions | lloc\Msls\Options\Options |
lloc\Msls\MslsOptionsPost | lloc\Msls\Options\Post\Post |
lloc\Msls\MslsOptionsTax | lloc\Msls\Options\Tax\Tax |
lloc\Msls\MslsOptionsQuery | lloc\Msls\Options\Query\Query |
lloc\Msls\MslsOutput | lloc\Msls\Frontend\Output |
lloc\Msls\MslsLink | lloc\Msls\Link\Link |
lloc\Msls\MslsLinkTextOnly | lloc\Msls\Link\TextOnly |
lloc\Msls\MslsLinkImageOnly | lloc\Msls\Link\ImageOnly |
lloc\Msls\MslsLinkTextImage | lloc\Msls\Link\TextImage |
lloc\Msls\MslsAdmin | lloc\Msls\Admin\Admin |
lloc\Msls\MslsPostType | lloc\Msls\ContentTypes\PostType |
lloc\Msls\MslsTaxonomy | lloc\Msls\ContentTypes\Taxonomy |
Die vollständige Zuordnung steht als Konstante MAP in includes/Compat/Aliases.php.
Am besten fahren Sie ohnehin, wenn Sie die Klassen gar nicht direkt anfassen: Für fast alles gibt es eine msls_*()-Funktion, die den Zugriff kapselt und stabil bleibt.
Wie es weitergeht
- API-Funktionen: die öffentlichen Funktionen des Plugins, mit Signatur und Zweck
- Snippets & Beispiele: kurze Rezepte für Template, Menü,
hreflangund Quick Create - Hook-Referenz: alle Actions und Filter, nach Subsystem gruppiert
Fragen, Fehler und Vorschläge gehören ins Issue-Tracking auf GitHub oder ins Support-Forum auf WordPress.org.
Der Artikel ist auch in English verfügbar.