wp_set_script_translations()

Définition : wp_set_script_translations() associe un catalogue de traductions JavaScript à un script WordPress enregistré. Elle permet aux chaînes déclarées avec les fonctions de localisation JavaScript d’utiliser la langue active.

Comprendre et utiliser

À quoi sert ce terme ?

Elle évite de traduire manuellement chaque message de l’interface éditoriale. Un plugin distribué peut fournir des traductions cohérentes à ses scripts sans coder des conditions pour chaque langue.

Fonctionnement technique

La fonction reçoit le handle du script, son domaine textdomain et éventuellement un dossier de traductions. Le système doit trouver des fichiers de traduction JavaScript appropriés pour la locale concernée.

Dans quels contextes l’utiliser ?

À utiliser pour les scripts classiques construits avec @wordpress/i18n. Il faut générer ou fournir les catalogues attendus et vérifier les conventions de noms.

Cas concret : ATOOLPHA

ATOOLPHA traduit un panneau d’édition dont les messages sont écrits avec __() en JavaScript et doivent suivre la locale d’administration.

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( 'enqueue_block_editor_assets', function () {
    wp_enqueue_script(
        'atoolpha-editor',
        plugin_dir_url( __FILE__ ) . 'build/editor.js',
        array( 'wp-i18n' ), '1.0.0', true
    );
    wp_set_script_translations(
        'atoolpha-editor', 'atoolpha',
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

Décryptage de l’exemple

Le script déclare wp-i18n parmi ses dépendances ; l’association des traductions utilise exactement son handle et son domaine. Les fichiers de langue doivent exister et correspondre au build réel.

Résultat attendu

Le panneau peut afficher ses chaînes traduites lorsque les catalogues attendus sont disponibles pour la locale.

Exercice pratique et vérification

Construire une chaîne traduisible dans un fichier JS de démonstration, générer sa traduction et comparer l’affichage pour deux locales.

Précautions et limites

La simple présence du dossier languages ne garantit aucun résultat : les fichiers JSON de traduction doivent être générés dans le format attendu et correctement nommés.

À ne pas confondre

wp_set_script_translations() lie un catalogue à un script ; wp_localize_script() fournit notamment un objet de chaînes ; les deux ne remplacent pas automatiquement l’autre.

Diagnostic avancé

En cas de textes non traduits, vérifier le domaine, le handle, la locale, les catalogues JS et la génération des fichiers, puis inspecter les requêtes réseau.

Choix d’architecture et déploiement

L’internationalisation JavaScript dépend de la chaîne complète : extraction, génération JSON, nom de fichier, handle, textdomain et locale. Une extension fonctionnelle en langue par défaut n’est pas automatiquement prête pour la distribution multilingue ; tester le build livré.