Documentazione Universally

Guide passo-passo, suggerimenti SEO multilingue e best practice per aiutarti a tradurre e scalare il tuo sito WordPress.

Crea un selettore di lingua personalizzato in WordPress

Universally viene fornito con un selettore a discesa integrato che puoi inserire tramite posizionamento automatico, lo shortcode [universally_switcher] o la funzione PHP universally_switcher(). Questo copre la maggior parte dei casi.

Ma se vuoi pieno controllo su come il selettore appare e si comporta: una riga di schede inline, pulsanti solo con bandierine, un elenco verticale in una barra laterale, un menu a discesa personalizzato che corrisponde al tuo design system, qualsiasi cosa. Puoi costruirne uno tuo in PHP usando gli stessi dati che il plugin usa internamente.

Questa guida ti mostra:

  1. Le basi: l'unica funzione di supporto di cui hai bisogno, i dati che restituisce e un selettore minimale "Hello World" su cui puoi costruire.
  2. Un esempio completo funzionante: schede inline (bandierine + nomi nativi) con opzioni di allineamento, toggle e stili, che puoi usare così come sono o adattare.

Le basi

Universally espone una singola funzione di supporto PHP che restituisce tutto ciò di cui hai bisogno per visualizzare un selettore:

universally_get_switcher_urls();

Restituisce un array di voci di lingua. Ogni voce contiene:

Campo Tipo Descrizione
nome string Nome visualizzato in inglese, con la regione o la variante tra parentesi (es. Spagnolo (Messico), Inglese (Britannico)).
originalName string Solo nome nativo, nessuna regione (es. Deutsch, English, Français).
flagUrl string URL dell'icona della bandierina, o una stringa vuota quando nessuna bandierina è associata alla regione. Sempre presente, indipendentemente dall'impostazione "Country Flags".
urlPrefix string Prefisso URL per la lingua (es. de, fr, mx). Vuoto per la lingua di origine.
lingua string Codice lingua base (es. es, en).
variant string Variante di traduzione, in minuscolo (es. es-419, en-gb). Vuoto per la lingua di origine.
region string Codice regione completo, in minuscolo (es. es-mx, de-de). Non un codice paese base.
isSource bool true per la lingua sorgente.
disabilitato bool true quando la lingua è aggiunta ma disabilitata. Solo lingue di destinazione.
url string URL completo della pagina corrente in questa lingua.
isCurrent bool true per la lingua attualmente visualizzata dal visitatore.

Salta le lingue disabilitate. Una lingua disabilitata appare ancora in questo array, ma il suo URL non viene più servito come traduzione, quindi un link ad essa è un vicolo cieco. Il selettore integrato le filtra e anche il tuo selettore dovrebbe farlo: questo è il controllo isDisabled negli esempi seguenti.

Usa region quando hai bisogno di un valore locale per un attributo lang o un hreflang, poiché è il codice completo anziché un'abbreviazione di paese.

Una volta che hai questo array, il resto dipende da te: in quale HTML lo inserisci, quale CSS applichi, quale comportamento aggiungi. Universally non si preoccupa.

Esempio di base minimale

Il più piccolo switcher personalizzato possibile: scorri le lingue, genera un link per ciascuna, esponilo come shortcode. Nessuno stile, nessuna opzione, nessun markup oltre a quanto richiesto.

<?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');

Incolla questo nel functions.php del tuo tema child (o in un plugin per snippet di codice come WPCode) e usalo ovunque siano accettati gli shortcode:

[custom_language_switcher]

...o chiamalo da PHP (ad esempio in un file di template del tema):

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

Questa è la base. Da qui puoi:

  • Aggiungere CSS per disporlo come preferisci (riga di schede, menu verticale, griglia…).
  • Aggiungere attributi allo shortcode per renderlo configurabile.
  • Evidenziare la lingua corrente usando $lang['isCurrent'].
  • Nascondere la lingua di origine, mostrare solo determinate lingue, raggrupparle, ecc.

L'esempio pratico qui sotto mostra come può apparire in pratica.

Esempio funzionante: schede lingua inline

Un selettore personalizzato completo basato sulle basi sopra. Renderizza le lingue come una riga orizzontale di schede con bandierine e nomi nativi, utile per posizionarlo in un'intestazione, accanto a una barra di ricerca, o ovunque tu voglia un selettore non a discesa.

Aggiunge:

  • Tre opzioni di allineamento: left, right, center.
  • Toggle per bandiere e nomi indipendentemente (ad esempio, solo bandiere).
  • CSS integrato in modo che appaia corretto senza che tu debba scrivere alcuno stile.
  • Evidenzia la lingua corrente con aria-current="page" e una classe --current per lo styling.
  • Classi con namespace (custom-uni-tabs*) in modo che non vadano in conflitto con nient'altro.

⚠️ Usa questo OPPURE lo snippet di base sopra, non entrambi contemporaneamente, perché entrambi definirebbero uno shortcode. (Puoi rinominare uno dei due per usarli fianco a fianco.)

Aggiungi lo snippet

Incolla questo nel functions.php del tuo tema child (o WPCode):

<?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');

Usalo

Shortcode

[custom_uni_tabs]

Attributi:

Attributo Valori Predefinito Cosa fa
allinea sinistra, destra, centro centro Allineamento orizzontale della riga.
show_flags true, false true Mostra/nascondi icone bandiera.
show_names true, false true Mostra/nascondi nomi delle lingue native.

Esempi:

[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

Per quando vuoi inserirlo direttamente in un file di template del tema (ad es. header.php), in un hook o in un widget PHP/codice del page builder. Chiama direttamente la funzione e passa eventuali attributi come array:

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

⚠️ Modifica header.php (o qualsiasi file del tema principale) solo all'interno di un tema child. La modifica diretta del tema principale significa che le tue modifiche andranno perse la prossima volta che il tema verrà aggiornato.

Override CSS opzionali

L'esempio include impostazioni predefinite sensate. Sovrascrivile dal foglio di stile del tuo tema ogni volta che ne hai bisogno:

/* 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; }

Riferimento classi:

Classe Applicato a
.custom-uni-tabs La <ul> esterna.
.custom-uni-tabs--left/right/center Modificatore di allineamento sulla <ul>.
.custom-uni-tabs__item Ogni <li>.
.custom-uni-tabs__link Ogni <a> (inline-block, nessun padding).
.custom-uni-tabs__link--current Il link della lingua attiva.
.custom-uni-tabs__flag La <img> della bandiera.
.custom-uni-tabs__flag--with-label Bandiera quando mostrata accanto a un nome.
.custom-uni-tabs__label Il nome nativo <span>.

Dove posizionare lo switcher

Una volta registrato il tuo shortcode, puoi posizionarlo ovunque nel tuo sito. I passaggi esatti dipendono dal tuo tema/builder:

  • Temi a blocchi (Twenty Twenty-Four, ecc.): apri Aspetto → Editor, trova il template o la parte di template che vuoi modificare (es. Intestazione, Piè di pagina, una singola pagina), inserisci un blocco Shortcode e incolla [custom_uni_tabs].
  • Page builder (Elementor / Divi / Beaver Builder / Bricks): aggiungi un widget Shortcode o Codice ovunque tu voglia il selettore e incolla [custom_uni_tabs].
  • Temi classici: incolla [custom_uni_tabs] direttamente in un post, pagina o area widget. Per inserirlo all'interno di un file di template del tema (es. header.php, footer.php, sidebar.php), modifica il file in un tema child e aggiungi:
<?php if (function_exists('custom_uni_tabs')) echo custom_uni_tabs(); ?>

Risoluzione dei problemi

Non compare nulla. Assicurati che il plugin Universally sia attivo e che almeno una lingua di destinazione sia abilitata nel tuo progetto. Gli snippet non restituiscono nulla quando universally_get_switcher_urls() non è disponibile o è vuoto.

L'elenco è vuoto o obsoleto. L'elenco delle lingue viene memorizzato nella cache del tuo sito per 15 minuti. L'aggiunta o la rimozione di una lingua normalmente la aggiorna immediatamente, ma tale invio non può raggiungere un sito che Universally non può raggiungere: un'installazione locale o di staging, un host con firewall, un progetto senza dominio impostato o una richiesta che è andata in timeout. Un sito appena connesso potrebbe ancora avere un elenco vuoto. L'apertura di Universally » Generale » Lingue forza un aggiornamento. Il salvataggio delle impostazioni del plugin non lo fa.

Non vengono visualizzate bandiere. L'impostazione Bandiere Nazionali non influisce su un selettore personalizzato: si applica solo a quello integrato. Verifica invece se flagUrl è vuoto per quella lingua, il che accade quando nessuna bandiera è mappata per la sua regione. L'impostazione si trova in Universally » Selettore Lingua » Bandiere Nazionali se desideri modificare anche il selettore integrato.

I visitatori non possono tornare alla lingua di origine. La visualizzazione di un URL tradotto memorizza la lingua del visitatore per 30 giorni e gli URL senza prefisso reindirizzano ad essa. Il selettore integrato aggira questo problema aggiungendo ?universally_switch=source al link della lingua di origine, il che cancella la scelta memorizzata. Riproduci questo nel tuo selettore:

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

Le schede non sono allineate come previsto. Nell'esempio funzionante, l'attributo align posiziona gli elementi all'interno di <ul>, ma <ul> stesso occupa solo la larghezza del suo contenitore padre. Se il padre non è a larghezza intera, le schede potrebbero apparire decentrate o spostate su un lato. Involucra lo shortcode in un contenitore a larghezza intera, o aggiungi:

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

Il selettore mobile predefinito è ancora visibile. Vai su Universally → Selettore Lingua e cambia l'implementazione da Automatico a Personalizzato, altrimenti appariranno entrambi.

Errore “Cannot redeclare function”. Hai incollato due snippet che definiscono lo stesso nome di funzione. Conservane solo uno, o rinominane uno.

È stato utile?