Documentation Universally

Guides étape par étape, conseils de SEO multilingue et meilleures pratiques pour vous aider à traduire et à développer votre site WordPress.

Créer un sélecteur de langue personnalisé dans WordPress

Universally est livré avec un sélecteur déroulant intégré que vous pouvez intégrer via le placement automatique, le shortcode [universally_switcher], ou la fonction PHP universally_switcher(). Cela couvre la plupart des cas.

Mais si vous voulez un contrôle total sur l'apparence et le comportement du sélecteur : une rangée d'onglets en ligne, des boutons avec uniquement les drapeaux, une liste verticale dans une barre latérale, un menu déroulant personnalisé qui correspond à votre système de design, n'importe quoi. Vous pouvez créer le vôtre en PHP en utilisant les mêmes données que le plugin utilise en interne.

Ce guide vous montre :

Les bases : la seule fonction d'aide dont vous avez besoin, les données qu'elle renvoie et un sélecteur minimal « Hello World » sur lequel vous pouvez construire.
Un exemple complet : onglets en ligne (drapeaux + noms natifs) avec options d'alignement, bascules et styles, que vous pouvez utiliser tels quels ou adapter.

Les bases

Universally expose une seule fonction d'aide PHP qui renvoie tout ce dont vous avez besoin pour afficher un sélecteur :

universally_get_switcher_urls();

Elle renvoie un tableau d'entrées de langue. Chaque entrée contient :

Champ	Type	Description
`nom`	chaîne de caractères	Nom d'affichage en anglais, avec la région ou la variante entre crochets (par ex. Espagnol (Mexique), Anglais (Britannique)).
`nom original`	chaîne de caractères	Nom natif uniquement, sans région (par ex. Deutsch, English, Français).
`URL du drapeau`	chaîne de caractères	URL de l'icône du drapeau, ou une chaîne vide lorsqu'aucun drapeau n'est mappé pour la région. Toujours présent, quoi que dise le paramètre Country Flags.
`préfixe d'URL`	chaîne de caractères	Préfixe d'URL pour la langue (par ex. `de`, `fr`, `mx`). Vide pour la langue source.
`langue`	chaîne de caractères	Code de langue nu (par ex. `es`, `en`).
`variante`	chaîne de caractères	Variante de traduction, en minuscules (par ex. `es-419`, `en-gb`). Vide pour la langue source.
`région`	chaîne de caractères	Code de région complet, en minuscules (par ex. `es-mx`, `de-de`). Pas un code pays nu.
`est la source`	booléen	`true` pour la langue source.
`estDésactivé`	booléen	`true` lorsque la langue est ajoutée mais désactivée. Langues cibles uniquement.
`URL`	chaîne de caractères	URL complète de la page actuelle dans cette langue.
`est actuel`	booléen	`true` pour la langue que le visiteur consulte actuellement.

Ignorer les langues désactivées. Une langue désactivée apparaît toujours dans ce tableau, mais son URL n'est plus servie comme traduction, donc un lien vers celle-ci est une impasse. Le sélecteur intégré les filtre et votre sélecteur devrait faire de même : c'est la vérification isDisabled dans les exemples ci-dessous.

Utilisez region lorsque vous avez besoin d'une valeur locale pour un attribut lang ou un hreflang, car il s'agit du code complet plutôt qu'une abréviation de pays.

Une fois que vous avez ce tableau, le reste dépend de vous : dans quel HTML vous l'encapsulez, quelle CSS vous appliquez, quel comportement vous ajoutez. Universally s'en fiche.

Exemple de base minimale

Le plus petit sélecteur personnalisé possible : parcourez les langues, affichez un lien pour chacune, exposez-le sous forme de shortcode. Pas de styles, pas d'options, pas de balisage au-delà de ce qui est requis.

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

Collez ceci dans le functions.php de votre thème enfant (ou un plugin d'extraits de code comme WPCode) et utilisez-le partout où les shortcodes sont acceptés :

[custom_language_switcher]

...ou appelez-le depuis PHP (par exemple dans un fichier de modèle de thème) :

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

C'est la base. À partir de là, vous pouvez :

Ajouter du CSS pour le disposer comme vous le souhaitez (rangée d'onglets, menu vertical, grille...).
Ajouter des attributs de shortcode pour le rendre configurable.
Mettre en surbrillance la langue actuelle à l'aide de $lang['isCurrent'].
Masquer la langue source, n'afficher que certaines langues, les regrouper, etc.

L'exemple fonctionnel ci-dessous montre à quoi cela peut ressembler en pratique.

Exemple concret : onglets de langue en ligne

Un sélecteur personnalisé complet basé sur les fondations ci-dessus. Il affiche les langues sous forme d'une rangée horizontale d'onglets avec des drapeaux et des noms natifs, utile pour le placer dans un en-tête, à côté d'une barre de recherche, ou n'importe où ailleurs où vous souhaitez un sélecteur autre qu'un menu déroulant.

Il ajoute :

Trois options d'alignement : left, right, center.
Des bascules pour les drapeaux et les noms indépendamment (par exemple, uniquement les drapeaux).
CSS intégré pour qu'il s'affiche correctement sans que vous ayez à écrire de styles.
Met en surbrillance la langue actuelle avec aria-current="page" et une classe --current pour le style.
Classes avec espace de noms (custom-uni-tabs*) pour qu'il n'entre pas en collision avec autre chose.

⚠️ Utilisez ceci OU l'extrait de base ci-dessus, pas les deux en même temps, car ils définiraient tous deux un shortcode. (Vous pouvez renommer l'un d'eux pour les utiliser côte à côte.)

Ajouter l'extrait

Collez ceci dans le functions.php de votre thème enfant (ou 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');

Utilisez-le

Code court

[custom_uni_tabs]

Attributs :

Attribut	Valeurs	Défaut	Ce que ça fait
`aligner`	`gauche`, `droite`, `centre`	`centre`	Alignement horizontal de la ligne.
`afficher les drapeaux`	`vrai`, `faux`	`vrai`	Afficher/masquer les icônes des drapeaux.
`afficher les noms`	`vrai`, `faux`	`vrai`	Afficher/masquer les noms de langue natifs.

Exemples :

[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

Pour lorsque vous souhaitez l'insérer directement dans un fichier de modèle de thème (par exemple, header.php), dans un hook, ou dans un widget PHP/code de constructeur de page. Appelez directement la fonction et passez tous les attributs sous forme de tableau :

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

⚠️ Modifiez header.php (ou tout fichier de thème principal) uniquement dans un thème enfant. La modification directe du thème parent signifie que vos modifications seront perdues lors de la prochaine mise à jour du thème.

Surcharges CSS optionnelles

L'exemple est livré avec des valeurs par défaut raisonnables. Remplacez-les à partir de votre feuille de style de thème chaque fois que vous en avez besoin :

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

Référence des classes :

Classe	Appliqué à
`.custom-uni-tabs`	La `<ul>` externe.
`.custom-uni-tabs--gauche/droite/centre`	Modificateur d'alignement sur la `<ul>`.
`.custom-uni-tabs__item`	Chaque `<li>`.
`.custom-uni-tabs__link`	Chaque `<a>` (inline-block, pas de padding).
`.custom-uni-tabs__link--actuel`	Le lien de la langue active.
`.custom-uni-tabs__flag`	Le drapeau `<img>`.
`.custom-uni-tabs__flag--avec-label`	Drapeau lorsqu'il est affiché à côté d'un nom.
`.custom-uni-tabs__label`	Le nom natif `<span>`.

Où placer le sélecteur

Une fois votre shortcode enregistré, vous pouvez le placer n'importe où sur votre site. Les étapes exactes dépendent de votre thème/constructeur :

Thèmes de bloc (Twenty Twenty-Four, etc.) : ouvrez Apparence → Éditeur, trouvez le modèle ou la partie de modèle que vous souhaitez modifier (par ex. En-tête, Pied de page, une page unique), insérez un bloc Shortcode et collez [custom_uni_tabs].
Constructeurs de pages (Elementor / Divi / Beaver Builder / Bricks) : ajoutez un widget Shortcode ou Code là où vous souhaitez le sélecteur et collez [custom_uni_tabs].
Thèmes classiques : collez [custom_uni_tabs] directement dans un article, une page ou une zone de widget. Pour le placer dans un fichier de modèle de thème (par ex. header.php, footer.php, sidebar.php), modifiez le fichier dans un thème enfant et ajoutez :

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

Dépannage

Rien ne s'affiche. Assurez-vous que le plugin Universally est actif et qu'au moins une langue cible est activée dans votre projet. Les extraits ne renvoient rien lorsque universally_get_switcher_urls() est indisponible ou vide.

La liste est vide ou obsolète. La liste des langues est mise en cache sur votre site pendant 15 minutes. L'ajout ou la suppression d'une langue la rafraîchit normalement immédiatement, mais cette poussée ne peut pas atteindre un site que Universally ne peut pas atteindre : une installation locale ou de staging, un hôte protégé par un pare-feu, un projet sans domaine défini ou une requête qui a expiré. Un site qui vient d'être connecté peut également encore détenir une liste vide. L'ouverture de Universally » Général » Langues force un rafraîchissement. La sauvegarde des paramètres du plugin ne le fait pas.

Aucun drapeau ne s'affiche. Le paramètre Drapeaux de pays n'affecte pas un sélecteur personnalisé : il s'applique uniquement à celui intégré. Vérifiez si flagUrl est vide pour cette langue à la place, ce qui se produit lorsqu'aucun drapeau n'est mappé pour sa région. Le paramètre se trouve dans Universally » Sélecteur de langue » Drapeaux de pays si vous souhaitez également modifier le sélecteur intégré.

Les visiteurs ne peuvent pas revenir à la langue source. La visualisation d'une URL traduite stocke la langue du visiteur pendant 30 jours, et les URL sans préfixe y redirigent ensuite. Le sélecteur intégré contourne cela en ajoutant ?universally_switch=source au lien de la langue source, ce qui efface le choix stocké. Reproduisez cela dans votre propre sélecteur :

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

Les onglets ne s'alignent pas comme prévu. Dans l'exemple fonctionnel, l'attribut align positionne les éléments à l'intérieur de <ul>, mais le <ul> lui-même ne prend que la largeur de son conteneur parent. Si le parent n'est pas pleine largeur, les onglets peuvent sembler décentrés ou décalés sur un côté. Encapsulez le shortcode dans un conteneur pleine largeur, ou ajoutez :

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

Le sélecteur flottant par défaut s'affiche toujours. Accédez à Universally → Sélecteur de langue et changez l'implémentation de Auto à Personnalisé, sinon les deux apparaîtront.

Erreur « Impossible de redéclarer la fonction ». Vous avez collé deux extraits qui définissent le même nom de fonction. Gardez-en un seul, ou renommez l'un d'eux.

Est-ce que cela vous a été utile ?