API-Funktionen - Multisite Language Switcher

Der Multisite Language Switcher bringt eine kleine Sammlung globaler Hilfsfunktionen mit, die zusammen die öffentliche API des Plugins bilden. Sie liegen in includes/api.php und stehen bereit, sobald WordPress die Plugin-Datei einbindet, also noch vor plugins_loaded und unabhängig davon, in welcher Reihenfolge die Plugins geladen werden.

Verwenden Sie diese Funktionen in Templates, Shortcodes, Blöcken oder eigenen Plugins, wann immer Sie den Umschalter ausgeben, eine Übersetzungs-URL auflösen oder auf Daten des Plugins zugreifen wollen. Die Funktionen kapseln die Registry-Funktionalitäten des Plugins; ein wiederholter Aufruf ist daher performant und unproblematisch.

In Theme-Templates empfiehlt sich ein function_exists()-Test, damit Ihr Theme auch dann noch funktioniert, wenn das Plugin deaktiviert wird:

if ( function_exists( 'msls_the_switcher' ) ) {
	msls_the_switcher();
}

Hinweis für Umsteiger: Alle Funktionsnamen haben sich mit Version 2.10.1 geändert. get_the_msls(), the_msls(), get_msls_flag_url(), get_msls_blog_description() und get_msls_permalink() funktionieren weiterhin, geben aber eine Deprecation-Meldung aus. Die Zuordnung steht unten im Abschnitt „Überholte Funktionen“.

Den Switcher ausgeben

msls_the_switcher

msls_the_switcher( array $arr = array() ): void

Gibt den Sprachumschalter im Template aus. Das optionale Array wird als Tag-Überschreibung an das Output-Objekt weitergegeben: before_output, after_output, before_item und after_item. So können Sie den Umschalter in einem einzelnen Template in eigenes Markup verpacken, ohne die globalen Einstellungen des Plugins anzufassen.

msls_the_switcher(
	array(
		'before_output' => '<ul class="language-nav">',
		'after_output'  => '</ul>',
		'before_item'   => '<li>',
		'after_item'    => '</li>',
	)
);

msls_get_switcher

msls_get_switcher( mixed $attr = array() ): string

Liefert denselben Umschalter als String zurück, anstatt ihn auszugeben. Praktisch, wenn Sie das Markup in einen anderen String einbetten, aus einem eigenen Shortcode zurückgeben oder durch Ihre eigene Escaping-Logik schicken wollen. Das Argument verhält sich wie bei msls_the_switcher(); seit 3.0 ist es optional.

$markup = msls_get_switcher();

Das ist auch die Funktion hinter dem Shortcode

Deutsch
English

Übersetzungen auflösen

msls_get_permalink

msls_get_permalink( string $locale, string $preset = '' ): string

Liefert die URL der Übersetzung des aktuellen Objekts (Beitrag, Term oder Archiv) in der Sprache des angegebenen Locale. Existiert keine Übersetzung, kommt $preset zurück, typischerweise ein leerer String oder eine Fallback-URL. Das ist die richtige Funktion, wenn Sie einen einzelnen, direkten Link auf eine Sprache setzen oder Ihr eigenes Umschalter-Markup bauen wollen.

$url = msls_get_permalink( 'de_DE', home_url( '/' ) );

msls_get_flag_url

msls_get_flag_url( string $locale ): string

Liefert die URL des Flaggen-Icons für ein Locale. Das Verzeichnis lässt sich über den Filter msls_options_get_flag_url umbiegen, der Dateiname über msls_options_get_flag_icon. Die Funktion zeigt also immer auf die konfigurierte Icon-Quelle.

msls_get_blog_description

msls_get_blog_description( string $locale, string $preset = '' ): string

Liefert die Beschreibung, die für den Blog dieses Locale konfiguriert ist. Es ist derselbe Wert, den das Plugin als Sprachbezeichnung verwendet. Ist für das Locale kein Blog registriert, kommt $preset zurück.

msls_blog

msls_blog( string $locale ): ?\lloc\Msls\Blog\Blog

Löst ein Locale in seine Blog-Instanz auf, oder null, wenn kein Blog mit diesem Locale zur Collection gehört. Nutzen Sie die Funktion, wenn Sie direkten Zugriff auf einen einzelnen Blog brauchen, etwa für get_url() in einem eigenen Umschalter, und den Fall „kein Blog“ selbst behandeln wollen.

$blog = msls_blog( 'fr_FR' );
if ( $blog ) {
	echo esc_html( $blog->get_description() );
}

Dienste des Plugins

msls_blog_collection

msls_blog_collection(): \lloc\Msls\Blog\Collection

Liefert das Singleton Blog\Collection, das alle Blogs abbildet, die das Plugin verwaltet, mit ihren Locales, Beschreibungen, URLs und dem aktuellen Blog. Die erste Wahl, wenn Sie selbst über die Sprachen iterieren wollen.

Die wichtigsten Methoden:

get(): alle Blogs außer dem aktuellen
get_objects(): alle Blogs einschließlich des aktuellen
get_current_blog(): der Blog, in dem der Request läuft
get_blog( string $language ): ein Blog anhand seines Locale
get_blog_id( string $language ): nur die Blog-ID dazu

msls_options

msls_options(): \lloc\Msls\Options\Options

Liefert das globale Options-Singleton, also die zusammengeführten Plugin-Einstellungen für den aktuellen Request. Damit lesen Sie Konfigurationswerte wie die Darstellungsart, die überschriebene Bild-URL oder die Frage, ob der aktuelle Blog im Umschalter erscheint.

msls_output

msls_output(): \lloc\Msls\Frontend\Output

Liefert eine frische Frontend\Output-Instanz für den aktuellen Request, dasselbe Objekt, das msls_the_switcher() und msls_get_switcher() intern verwenden. Rufen Sie es direkt auf, wenn Sie die Links einzeln brauchen, statt sie als fertigen String zu bekommen:

$links = msls_output()->get( 2 ); // Array von <a>-Elementen, nur Flaggen

Das Argument von get() wählt die Darstellungsvariante: 0 Flagge und Text, 1 nur Text, 2 nur Flagge, 3 Text und Flagge.

msls_content_types

msls_content_types(): \lloc\Msls\ContentTypes\ContentTypes

Liefert die ContentTypes\ContentTypes-Instanz, eine kontextbewusste Factory für die unterstützten Post Types und Taxonomien. Damit können Sie fragen „ist der aktuelle Request ein übersetzbarer Inhaltstyp?“, ohne selbst zu unterscheiden, ob Sie auf einer Beitrags- oder einer Taxonomie-Seite stehen.

msls_post_type

msls_post_type(): \lloc\Msls\ContentTypes\PostType

Liefert das Singleton ContentTypes\PostType mit der Liste der Post Types, die das Plugin als übersetzbar behandelt. Die Liste selbst lässt sich über den Filter msls_supported_post_types verändern.

msls_taxonomy

msls_taxonomy(): \lloc\Msls\ContentTypes\Taxonomy

Das Gegenstück für Taxonomien; der zugehörige Filter heißt msls_supported_taxonomies.

Übersetzungsdaten einzelner Objekte

msls_get_post

msls_get_post( int $id ): \lloc\Msls\Options\Post\Post

Liefert die Options\Post\Post-Instanz für eine Beitrags-ID. Das Objekt kennt die Übersetzungszuordnung des Beitrags, also die IDs der entsprechenden Beiträge in den anderen Blogs, und bietet get_postlink( $language ) für die URL einer einzelnen Sprache.

$link = msls_get_post( get_the_ID() )->get_postlink( 'it_IT' );

msls_get_tax

msls_get_tax( int $id ): \lloc\Msls\Options\Tax\OptionsTaxInterface

Liefert das Übersetzungsobjekt für eine Term-ID. Je nach aktueller Abfrage (Kategorie, Schlagwort oder eigene Taxonomie) bekommen Sie die passende Unterklasse zurück, ohne die Kontexterkennung selbst schreiben zu müssen.

msls_get_query

msls_get_query(): ?\lloc\Msls\Options\Query\Query

Liefert das Options\Query\Query-Objekt für den aktuellen Archiv-Request (Tag, Monat, Jahr, Autor oder Post-Type-Archiv) oder null, wenn der Request kein Archiv ist. msls_get_permalink() kapselt diesen Fall bereits; die Funktion ist dann interessant, wenn Sie das Archiv genauer auswerten wollen.

Interner Helfer

msls_return_void

msls_return_void(): void

Eine leere Funktion. Sie existiert, damit Aufrufer, typischerweise Registrierungen von WordPress-Actions, ein Callable übergeben können, das nichts tut, ohne dafür eine Closure zu erfinden. Für die Anwendung im eigenen Code gibt es keinen Grund; hier nur der Vollständigkeit halber erwähnt.

Überholte Funktionen

Die folgenden Namen aus der Zeit vor 2.10.1 leben in includes/deprecated.php weiter. Jeder Aufruf funktioniert, löst aber _deprecated_function() aus und leitet an die moderne Entsprechung weiter. Stellen Sie Ihren Code bei Gelegenheit um.

Überholt seit 2.10.1	Nachfolger
`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 )`

Weiterlesen

Snippets & Beispiele: die Funktionen im Zusammenspiel
Hook-Referenz: alle Actions und Filter des Plugins

Der Artikel ist auch in English verfügbar.