wp_localize_script()

Définition : wp_localize_script() transmet des chaînes traduisibles associées à un script classique WordPress via un objet JavaScript. Elle sert notamment à fournir des textes d’interface dans la langue du visiteur.

Comprendre et utiliser

À quoi sert ce terme ?

Elle sépare les libellés visibles de la logique JavaScript et accompagne le système de traduction WordPress. Une extension peut ainsi exposer un message « Enregistrer » sans l’écrire uniquement en français dans le fichier .js.

Fonctionnement technique

Le script doit déjà être enregistré. L’objet JavaScript généré possède un nom unique et reçoit un tableau de données ; pour transmettre de simples configurations arbitraires, la documentation privilégie désormais wp_add_inline_script().

Dans quels contextes l’utiliser ?

L’utiliser pour les chaînes de localisation d’un script classique. Pour les paquets JavaScript modernes liés au système WordPress, étudier aussi @wordpress/i18n et wp_set_script_translations().

Cas concret : ATOOLPHA

Une petite interface de recherche ATOOLPHA affiche un texte traduit lorsque la recherche ne trouve aucun résultat.

Exemple de code commenté

Extrait PHP destiné à un plugin ou à un template WordPress, dans le contexte indiqué ; pas au contenu HTML de l’article.

<?php
add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_script(
        'atoolpha-search-ui',
        plugin_dir_url( __FILE__ ) . 'assets/search-ui.js',
        array(), '1.0.0', true
    );
    wp_localize_script( 'atoolpha-search-ui', 'atoolphaSearchL10n', array(
        'empty' => __( 'Aucun résultat.', 'atoolpha' ),
    ) );
} );

Décryptage de l’exemple

Après l’enqueue, WordPress peut imprimer l’objet atoolphaSearchL10n avant le script concerné. La chaîne utilise le domaine de traduction atoolpha, qui doit correspondre à la configuration réelle du plugin.

Résultat attendu

Le script peut lire atoolphaSearchL10n.empty et afficher la version disponible de ce message.

Exercice pratique et vérification

Charger le script de test et inspecter l’objet dans la console. Changer la locale de test et vérifier les traductions réellement disponibles.

Précautions et limites

Ne pas mettre de secrets ou de jetons privés dans cet objet : toutes les données sont visibles au navigateur. La fonction n’est pas une API de sécurité ni une autorisation de requête.

À ne pas confondre

wp_localize_script() fournit des textes localisés ; wp_add_inline_script() convient à la configuration arbitraire ; wp_set_script_translations() relie des catalogues JavaScript.

Diagnostic avancé

Si l’objet n’existe pas côté navigateur, vérifier l’ordre d’appel, le handle enregistré et l’impression de la ressource.

Choix d’architecture et déploiement

Pour les traductions, privilégier un catalogue de chaînes plutôt qu’un objet JavaScript servant de réservoir de paramètres applicatifs. Un code destiné au navigateur ne doit jamais recevoir de valeurs privées et doit rester fonctionnel même si une traduction manque.