Universally Dokumentation

Schritt-für-Schritt-Anleitungen, mehrsprachige SEO-Tipps und Best Practices, die Ihnen helfen, Ihre WordPress-Website zu übersetzen und zu skalieren.

Erstellen Sie einen benutzerdefinierten Sprachumschalter in WordPress

Universally wird mit einem integrierten Dropdown-Umschalter geliefert, den Sie per Auto-Platzierung, dem [universally_switcher] Shortcode oder der universally_switcher() PHP-Funktion einfügen können. Das deckt die meisten Fälle ab.

Aber wenn Sie vollständige Kontrolle darüber haben möchten, wie der Umschalter aussieht und sich verhält: eine Reihe von Inline-Tabs, reine Flaggen-Buttons, eine vertikale Sidebar-Liste, ein benutzerdefiniertes Dropdown, das zu Ihrem Designsystem passt, alles. Sie können Ihre eigenen in PHP erstellen, indem Sie dieselben Daten verwenden, die das Plugin intern nutzt.

Diese Anleitung zeigt Ihnen:

Die Grundlage: die eine Hilfsfunktion, die Sie benötigen, die Daten, die sie zurückgibt, und ein minimaler „Hallo Welt“-Umschalter, auf dem Sie aufbauen können.
Ein vollständiges Arbeitsbeispiel: Inline-Tabs (Flaggen + native Namen) mit Ausrichtungsoptionen, Toggles und Stilen, die Sie direkt verwenden oder anpassen können.

Die Grundlage

Universally stellt eine einzige PHP-Hilfsfunktion bereit, die alles zurückgibt, was Sie zum Rendern eines Umschalters benötigen:

universally_get_switcher_urls();

Es gibt ein Array von Spracheinträgen zurück. Jeder Eintrag enthält:

Feld	Typ	Beschreibung
`Name`	Zeichenkette	Englischer Anzeigename, mit der Region oder Variante in Klammern (z. B. Spanisch (Mexiko), Englisch (Britisch)).
`Originalname`	Zeichenkette	Nur nativer Name, keine Region (z. B. Deutsch, English, Français).
`Flaggen-URL`	Zeichenkette	URL zum Flaggen-Symbol oder eine leere Zeichenkette, wenn für die Region keine Flagge zugeordnet ist. Immer vorhanden, unabhängig von der Einstellung für Länderflaggen.
`URL-Präfix`	Zeichenkette	URL-Präfix für die Sprache (z. B. `de`, `fr`, `mx`). Leer für die Quellsprache.
`Sprache`	Zeichenkette	Bare Sprachcode (z. B. `es`, `en`).
`Variante`	Zeichenkette	Übersetzungsvariante, Kleinbuchstaben (z. B. `es-419`, `en-gb`). Leer für die Quellsprache.
`Region`	Zeichenkette	Vollständiger Regionscode, Kleinbuchstaben (z. B. `es-mx`, `de-de`). Kein bloßer Ländercode.
`IstQuelle`	Boolesch	`true` für die Quellsprache.
`istDeaktiviert`	Boolesch	`true`, wenn die Sprache hinzugefügt, aber deaktiviert ist. Nur für Zielsprachen.
`URL`	Zeichenkette	Vollständige URL zur aktuellen Seite in dieser Sprache.
`IstAktuell`	Boolesch	`true` für die Sprache, die der Besucher gerade ansieht.

Deaktivierte Sprachen überspringen. Eine deaktivierte Sprache erscheint immer noch in diesem Array, aber ihre URL wird nicht mehr als Übersetzung bereitgestellt, sodass ein Link dorthin ins Leere führt. Der integrierte Umschalter filtert sie heraus und Ihr Umschalter sollte dies ebenfalls tun: das ist die isDisabled-Prüfung in den folgenden Beispielen.

Verwenden Sie region, wenn Sie einen Locale-Wert für ein lang-Attribut oder ein hreflang benötigen, da dies der vollständige Code und keine Länderabkürzung ist.

Sobald Sie dieses Array haben, liegt der Rest bei Ihnen: in welches HTML Sie es einpacken, welches CSS Sie anwenden, welches Verhalten Sie hinzufügen. Universally ist das egal.

Minimales Grundgerüst-Beispiel

Der kleinstmögliche benutzerdefinierte Umschalter: Durchlaufen Sie die Sprachen, geben Sie für jede einen Link aus, stellen Sie ihn als Shortcode bereit. Keine Stile, keine Optionen, keine Markup über das Notwendige hinaus.

<?php
function custom_language_switcher() {
    if (!function_exists('universally_get_switcher_urls')) return '';
    $langs = universally_get_switcher_urls();
    if (empty($langs)) return '';

    $out = '<ul class="custom-language-switcher">';
    foreach ($langs as $lang) {
        if (empty($lang['url'])) continue;
        if (!empty($lang['isDisabled'])) continue;

        $label = esc_html($lang['originalName'] ?? '');
        $url   = esc_url($lang['url']);
        $flag  = !empty($lang['flagUrl'])
            ? '<img src="' . esc_url($lang['flagUrl']) . '" alt="">'
            : '';

        $out .= '<li><a href="' . $url . '">' . $flag . $label . '</a></li>';
    }
    $out .= '</ul>';

    return $out;
}
add_shortcode('custom_language_switcher', 'custom_language_switcher');

Fügen Sie dies in die functions.php Ihres Child-Themes (oder in ein Code-Snippets-Plugin wie WPCode) ein und verwenden Sie es überall dort, wo Shortcodes akzeptiert werden:

[custom_language_switcher]

...oder rufen Sie es aus PHP auf (z. B. in einer Theme-Template-Datei):

<?php if (function_exists('custom_language_switcher')) echo custom_language_switcher(); ?>

Das ist das Fundament. Von hier aus können Sie:

CSS hinzufügen, um es nach Belieben anzuordnen (Reihe von Tabs, vertikales Menü, Raster…).
Shortcode-Attribute hinzufügen, um es konfigurierbar zu machen.
Die aktuelle Sprache mit $lang['isCurrent'] hervorheben.
Die Quellsprache ausblenden, nur bestimmte Sprachen anzeigen, sie gruppieren usw.

Das nachfolgende ausgearbeitete Beispiel zeigt, wie das in der Praxis aussehen kann.

Arbeitsbeispiel: Inline-Sprach-Tabs

Ein voll funktionsfähiger benutzerdefinierter Umschalter, der auf der obigen Grundlage aufbaut. Er rendert die Sprachen als horizontale Reihe von Tabs mit Flaggen und nativen Namen, nützlich für die Platzierung in einer Kopfzeile, neben einer Suchleiste oder überall dort, wo Sie einen Umschalter ohne Dropdown wünschen.

Er fügt hinzu:

Drei Ausrichtungsoptionen: left, right, center.
Schalter für Flaggen und Namen unabhängig voneinander (z. B. nur Flaggen).
Integrierte CSS, damit es ohne eigene Stile gut aussieht.
Hebt die aktuelle Sprache mit aria-current="page" und einer --current-Klasse zur Gestaltung hervor.
Namensraumklassen (custom-uni-tabs*), damit es nicht mit anderen Dingen kollidiert.

⚠️ Verwenden Sie diesen ODER den obigen Foundation-Snippet, nicht beide gleichzeitig, da sie beide einen Shortcode definieren würden. (Sie können einen von beiden umbenennen, um sie nebeneinander zu verwenden.)

Fügen Sie den Snippet hinzu

Fügen Sie dies in die functions.php Ihres Child-Themes (oder WPCode) ein:

<?php
function custom_uni_tabs($atts = []) {
    if (!function_exists('universally_get_switcher_urls')) return '';
    $langs = universally_get_switcher_urls();
    if (empty($langs)) return '';

    $atts = shortcode_atts([
        'align'      => 'center',
        'show_flags' => 'true',
        'show_names' => 'true',
    ], $atts);

    $align     = in_array($atts['align'], ['left', 'right', 'center'], true) ? $atts['align'] : 'center';
    $showFlags = filter_var($atts['show_flags'], FILTER_VALIDATE_BOOLEAN);
    $showNames = filter_var($atts['show_names'], FILTER_VALIDATE_BOOLEAN);

    if (!$showFlags && !$showNames) {
        $showNames = true; // never render an empty link
    }

    static $printed_styles = false;
    $styles = '';
    if (!$printed_styles) {
        $printed_styles = true;
        $styles = '<style>
            .custom-uni-tabs { display: flex; align-items: center; gap: 16px; list-style: none; margin: 0; padding: 0; }
            .custom-uni-tabs--left   { justify-content: flex-start; }
            .custom-uni-tabs--right  { justify-content: flex-end; }
            .custom-uni-tabs--center { justify-content: center; }
            .custom-uni-tabs__item { margin: 0; padding: 0; }
            .custom-uni-tabs__link { display: inline-block; margin: 0; padding: 0; text-decoration: none; line-height: 1; }
            .custom-uni-tabs__link--current { font-weight: 600; }
            .custom-uni-tabs__flag { width: 20px; height: auto; vertical-align: middle; }
            .custom-uni-tabs__flag--with-label { margin-right: 6px; }
            .custom-uni-tabs__label { vertical-align: middle; }
        </style>';
    }

    $out = $styles . '<ul class="custom-uni-tabs custom-uni-tabs--' . esc_attr($align) . '">';
    foreach ($langs as $lang) {
        if (empty($lang['url'])) continue;
        if (!empty($lang['isDisabled'])) continue;

        $label = esc_html($lang['originalName'] ?? '');
        $url   = esc_url($lang['url']);
        $isCur = !empty($lang['isCurrent']);

        $flag = '';
        if ($showFlags && !empty($lang['flagUrl'])) {
            $flagCls = 'custom-uni-tabs__flag' . ($showNames ? ' custom-uni-tabs__flag--with-label' : '');
            $alt     = $showNames ? '' : $label;
            $flag    = '<img class="' . $flagCls . '" src="' . esc_url($lang['flagUrl']) . '" alt="' . esc_attr($alt) . '">';
        }

        $linkCls = 'custom-uni-tabs__link' . ($isCur ? ' custom-uni-tabs__link--current' : '');
        $aria    = $isCur ? ' aria-current="page"' : '';

        $out .= '<li class="custom-uni-tabs__item">';
        $out .= '<a class="' . $linkCls . '" href="' . $url . '"' . $aria . '>';
        $out .= $flag;
        if ($showNames) {
            $out .= '<span class="custom-uni-tabs__label">' . $label . '</span>';
        }
        $out .= '</a></li>';
    }
    $out .= '</ul>';

    return $out;
}
add_shortcode('custom_uni_tabs', 'custom_uni_tabs');

Verwenden Sie es

Kurzcode

[custom_uni_tabs]

Attribute:

Attribut	Werte	Standard	Was es tut
`ausrichten`	`links`, `rechts`, `mitte`	`mitte`	Horizontale Ausrichtung der Zeile.
`Flaggeanzeigen`	`wahr`, `falsch`	`wahr`	Flaggen-Icons anzeigen/ausblenden.
`Namenanzeigen`	`wahr`, `falsch`	`wahr`	Namen in Landessprache anzeigen/ausblenden.

Beispiele:

[custom_uni_tabs]
[custom_uni_tabs align="right"]
[custom_uni_tabs show_names="false"]               (flags only) 
[custom_uni_tabs show_flags="false" align="left"]  (names only, left)

PHP

Wenn Sie es direkt in eine Theme-Template-Datei (z. B. header.php), in einen Hook oder in ein Page-Builder-PHP/Code-Widget einfügen möchten. Rufen Sie die Funktion direkt auf und übergeben Sie alle Attribute als Array:

<?php
if (function_exists('custom_uni_tabs')) {
    echo custom_uni_tabs([
        'align'      => 'center',
        'show_flags' => 'true',
        'show_names' => 'false',
    ]);
}
?>

⚠️ Bearbeiten Sie header.php (oder eine beliebige Kernthemen-Datei) nur innerhalb eines Child Themes. Wenn Sie das Parent-Theme direkt bearbeiten, gehen Ihre Änderungen verloren, wenn das Theme das nächste Mal aktualisiert wird.

Optionale CSS-Überschreibungen

Das Beispiel wird mit sinnvollen Standardwerten geliefert. Überschreiben Sie diese in Ihrem Theme-Stylesheet, wann immer Sie möchten:

/* Bigger flags, more spacing, and a colour for the active language */
.custom-uni-tabs            { gap: 24px; }
.custom-uni-tabs__flag      { width: 24px; }
.custom-uni-tabs__link      { font-size: 14px; color: #333; }
.custom-uni-tabs__link:hover            { color: #000; }
.custom-uni-tabs__link--current         { color: #c00; font-weight: 700; }

Klassenreferenz:

Klasse	Angewendet auf
`.custom-uni-tabs`	Die äußere `<ul>`.
`.custom-uni-tabs--links/rechts/mitte`	Ausrichtungsmodifikator auf der `<ul>`.
`.custom-uni-tabs__item`	Jedes `<li>`.
`.custom-uni-tabs__link`	Jeder `<a>` (inline-block, keine Abstände).
`.custom-uni-tabs__link--aktuell`	Der Link der aktiven Sprache.
`.custom-uni-tabs__flag`	Das Flaggen-`<img>`.
`.custom-uni-tabs__flag--mit-beschriftung`	Flagge, wenn sie neben einem Namen angezeigt wird.
`.custom-uni-tabs__beschriftung`	Der native Name `<span>`.

Wo der Schalter platziert werden soll

Sobald Ihr Shortcode registriert ist, können Sie ihn überall auf Ihrer Website platzieren. Die genauen Schritte hängen von Ihrem Theme/Builder ab:

Block-Themes (Twenty Twenty-Four, etc.): Öffnen Sie Darstellung → Editor, suchen Sie die Vorlage oder das Vorlagenteil, das Sie bearbeiten möchten (z. B. Kopfzeile, Fußzeile, eine einzelne Seite), fügen Sie einen Shortcode-Block ein und fügen Sie [custom_uni_tabs] ein.
Page Builder (Elementor / Divi / Beaver Builder / Bricks): Fügen Sie ein Shortcode- oder Code-Widget hinzu, wo immer Sie den Umschalter wünschen, und fügen Sie [custom_uni_tabs] ein.
Klassische Themes: Fügen Sie [custom_uni_tabs] direkt in einen Beitrag, eine Seite oder einen Widget-Bereich ein. Um ihn in eine Theme-Vorlagendatei einzufügen (z. B. header.php, footer.php, sidebar.php), bearbeiten Sie die Datei in einem Child Theme und fügen Sie hinzu:

<?php if (function_exists('custom_uni_tabs')) echo custom_uni_tabs(); ?>

Fehlerbehebung

Nichts erscheint. Stellen Sie sicher, dass das Universally-Plugin aktiv ist und mindestens eine Zielsprache in Ihrem Projekt aktiviert ist. Die Snippets geben nichts zurück, wenn universally_get_switcher_urls() nicht verfügbar oder leer ist.

Die Liste ist leer oder veraltet. Die Sprachliste wird 15 Minuten lang auf Ihrer Website zwischengespeichert. Das Hinzufügen oder Entfernen einer Sprache aktualisiert sie normalerweise sofort, aber dieser Push kann eine Website nicht erreichen, die Universally nicht erreichen kann: eine lokale oder Staging-Installation, ein Host mit Firewall, ein Projekt ohne Domain oder eine Anfrage, die abgelaufen ist. Eine gerade erst verbundene Website kann auch immer noch eine leere Liste enthalten. Das Öffnen von Universally » Allgemein » Sprachen erzwingt eine Aktualisierung. Das Speichern der Plugin-Einstellungen tut dies nicht.

Keine Flaggen werden angezeigt. Die Einstellung für Länderflaggen wirkt sich nicht auf einen benutzerdefinierten Umschalter aus: Sie gilt nur für den integrierten. Prüfen Sie stattdessen, ob flagUrl für diese Sprache leer ist, was passiert, wenn für ihre Region keine Flagge zugeordnet ist. Die Einstellung befindet sich unter Universally » Sprachumschalter » Länderflaggen, wenn Sie auch den integrierten Umschalter ändern möchten.

Besucher können nicht zur Quellsprache zurückkehren. Das Anzeigen einer übersetzten URL speichert die Sprache des Besuchers für 30 Tage, und URLs ohne Präfix werden dann dorthin umgeleitet. Der integrierte Umschalter umgeht dies, indem er ?universally_switch=source zum Link der Quellsprache hinzufügt, was die gespeicherte Auswahl löscht. Reproduzieren Sie dies in Ihrem eigenen Umschalter:

$url = $lang['url'];
if (!empty($lang['isSource'])) {
    $url .= (strpos($url, '?') === false ? '?' : '&') . 'universally_switch=source';
}

Die Tabs werden nicht wie erwartet ausgerichtet. Im funktionierenden Beispiel positioniert das align-Attribut Elemente innerhalb der <ul>, aber die <ul> selbst nimmt nur die Breite ihres übergeordneten Containers ein. Wenn das übergeordnete Element nicht die volle Breite hat, können die Tabs dezentriert oder zu einer Seite verschoben aussehen. Umschließen Sie den Shortcode mit einem Container in voller Breite oder fügen Sie hinzu:

.custom-uni-tabs { width: 100%; }

Der standardmäßige schwebende Umschalter wird immer noch angezeigt. Gehen Sie zu Universally → Sprachumschalter und wechseln Sie die Implementierung von Auto auf Benutzerdefiniert, andernfalls werden beide angezeigt.

Fehler „Cannot redeclare function“. Sie haben zwei Snippets eingefügt, die denselben Funktionsnamen definieren. Behalten Sie nur eines bei oder benennen Sie eines davon um.

War das hilfreich?