Comment traduire les champs personnalisés ACF dans WordPress – Groupes de champs, répéteurs, pages d’Options

Avant de commencer

Installez et activez ces extensions :

• Advanced Custom Fields ou ACF Pro.
• WPML et WPML Traduction de chaînes.
• ACFML (le module complémentaire couvert par cette page).

Vos groupes de champs doivent déjà être configurés dans ACF. Vous pouvez modifier les préférences de traduction par champ par la suite, l’ordre des opérations n’a donc pas d’importance. Configurez les groupes de champs, puis revenez à ACFML.

Choisissez un mode de traduction pour chaque groupe de champs

Les groupes de champs ACF ne se comportent pas tous de la même manière lors de la traduction. ACFML propose trois modes par groupe de champs, définis dans ACF > Groupes de champs sous la section Configuration multilingue :

Mêmes champs dans toutes les langues

Le paramètre habituel pour la plupart des sites ACF. Traduisez les valeurs des champs dans chaque langue tout en conservant la même structure. La page Notre équipe en est l’exemple classique. Votre équipe est la même dans toutes les langues, de sorte que le nom et la biographie de chaque membre de l’équipe sont traduits par langue, tandis que la structure des champs reste intacte. Vous saisissez l’équipe dans la langue source, puis vous envoyez l’article pour traduction via WPML > Traductions > Tableau de bord ; les valeurs traduites reviennent attachées aux mêmes champs.

Champs différents selon les langues

À utiliser lorsque chaque langue affiche un contenu fondamentalement différent dans le même groupe de champs. Le cas classique est celui d’une entreprise qui organise des événements localisés. La page Événements en anglais affiche les événements destinés au public anglophone, la page en français affiche les événements destinés au public francophone. Réglez le groupe de champs sur Champs différents selon les langues, puis ouvrez l’article que vous souhaitez localiser > dans la boîte Langues à droite, cliquez sur l’icône plus pour la langue cible > un brouillon vierge s’ouvre avec des champs personnalisés vides > remplissez les valeurs spécifiques à la langue et publiez.

Mode expert

À utiliser lorsque vous avez besoin d’un mélange : certains champs sont traduits par langue, d’autres restent identiques, d’autres sont copiés une fois puis divergent. Choisissez le Mode expert dans la configuration du groupe de champs et définissez la préférence par champ. L’exemple des Événements avec un comportement mixte : le titre et la description sont réglés sur Traduire ; le prix, la date et l’adresse sont réglés sur Copier.

Préférences de traduction pour chaque type de champ ACF

Chaque champ d’un groupe de champs possède l’une des quatre préférences de traduction suivantes :

• Traduire. La valeur du champ est traduite par langue.
• Copier. La valeur du champ reste synchronisée dans toutes les langues ; modifiez-la une fois et elle se propage.
• Copier une fois. La valeur du champ sert de base à la traduction, puis chaque version linguistique peut être modifiée indépendamment.
• Ne pas traduire. Le champ est ignoré lors du processus de traduction.

Lorsque vous choisissez Mêmes champs dans toutes les langues ou Champs différents selon les langues, chaque champ reçoit une préférence par défaut cohérente avec son type. Les tableaux ci-dessous indiquent ces valeurs par défaut. Utilisez le Mode expert pour les redéfinir champ par champ, ou utilisez le filtre acfml_field_group_mode_field_translation_preference pour remplacer la valeur par défaut d’un type de champ sur l’ensemble du site (voir Hooks de développement pour les cas particuliers ci-dessous).

Répéteur et contenu flexible – Copier ou Copier une fois

Pour les champs Répéteur et Contenu flexible, vous devez choisir entre deux comportements au niveau des lignes avant que les préférences des sous-champs n’entrent en jeu :

• Copier. Même mise en page et même nombre de lignes dans toutes les langues. Les traducteurs voient les mêmes lignes ; les sous-champs sont traduits selon leurs propres préférences.
• Copier une fois. Chaque langue peut avoir une mise en page différente et un nombre de lignes différent après la copie initiale.

Choisissez Copier lorsque la structure est la même dans toutes les langues (dans la plupart des cas). Choisissez Copier une fois lorsque les versions linguistiques divergent sur le plan structurel (par exemple, une liste d’événements différente par langue).

Champs basiques

Champs de contenu

Champs de choix

Champs jQuery

Champs de mise en page

Champs relationnels

Définir les préférences pour les champs enregistrés en PHP ou JSON

Les groupes de champs ACF enregistrés en PHP (via acf_add_local_field_group()) ou via la fonctionnalité JSON local d’ACF ne récupèrent pas les préférences de traduction à partir de l’interface d’administration, car celle-ci ne les gère pas. Définissez les préférences là où vous enregistrez les champs.

Pour chaque champ de la définition du groupe de champs, ajoutez une clé wpml_cf_preferences. La valeur est un entier qui correspond aux quatre préférences de traduction : 0 pour Ne pas traduire (WPML ignore le champ), 1 pour Copier (la valeur reste synchronisée dans toutes les langues), 2 pour Traduire (la valeur passe par la traduction), et 3 pour Copier une fois (la valeur est copiée vers les nouvelles traductions, puis chaque langue peut être modifiée indépendamment).

Un exemple minimal :

acf_add_local_field_group( [
    'key'    => 'group_1',
    'title'  => 'My Group',
    'fields' => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'wpml_cf_preferences' => 2, // Translate.
        ],
    ],
    // ...rest of the field-group config
] );

Après avoir défini les champs dans le code, synchronisez les préférences dans WPML pour que l’interface d’administration les reconnaisse :

1. Accédez à ACF > Outils.
2. Faites défiler jusqu’à Traduire les champs ACF locaux JSON et enregistrés en PHP.
3. Dans Synchroniser les préférences de traduction pour les champs locaux, choisissez Synchroniser une fois maintenant et cliquez sur Appliquer.

WPML lit les préférences de vos définitions PHP et les enregistre. La synchronisation s’exécute une seule fois lorsque vous la déclenchez, et non à chaque chargement de page.

Si vous utilisez la fonctionnalité JSON local d’ACF pour partager des groupes de champs entre les sites, ACFML écrit automatiquement les préférences de traduction dans les fichiers JSON. Exportez un fichier JSON à partir d’un site, importez-le sur un autre, et le site de destination récupère les préférences une fois qu’ACFML est actif des deux côtés.

Traduire les étiquettes de champs ACF

Les étiquettes de champs ACF sont les noms qui identifient chaque champ personnalisé dans l’éditeur WordPress et sur le front-end (par exemple, Numéro de téléphone, Adresse). Elles sont traduites séparément des valeurs des champs, et elles se trouvent dans WPML Traduction de chaînes, et non dans la tâche de traduction de l’article.

Pour envoyer les étiquettes de champs à la traduction :

1. Ouvrez WPML > Traductions > Tableau de bord.
2. Développez la section Groupe de champs ACF.
3. Sélectionnez l’élément Étiquettes du groupe de champs pour le groupe de champs que vous souhaitez traduire.
4. Choisissez une méthode de traduction (PTC, votre traducteur ou Traduire moi-même) et envoyez.

Les étiquettes traduites apparaissent automatiquement sur le front-end une fois la traduction terminée.

Traduire les choix de champs ACF

Les champs de choix (Sélection, Case à cocher, Bouton radio, Groupe de boutons) comportent leurs propres étiquettes d’options (par exemple, Petit / Moyen / Grand). Elles se trouvent elles aussi aux côtés des étiquettes de champs, et non dans la traduction de l’article. Envoyez-les de la même manière :

1. Ouvrez WPML > Traductions > Tableau de bord.
2. Développez la section Groupe de champs ACF.
3. Sélectionnez le groupe de champs dont vous souhaitez traduire les valeurs de choix.
4. Choisissez une méthode de traduction et envoyez.

Traduire les pages d’Options ACF

Les pages d’Options ACF (les écrans de paramètres globaux tels que Coordonnées, Paramètres d’en-tête, Liens de pied de page) sont traduites comme un type d’objet à part entière, séparément des articles :

1. Ouvrez WPML > Traductions > Tableau de bord.
2. Développez la section Options ACF.
3. Sélectionnez la page d’Options que vous souhaitez traduire.
4. Choisissez une méthode de traduction et envoyez.

Les valeurs de la page d’Options de chaque langue s’affichent automatiquement lorsqu’ACF lit l’option dans le contexte de cette langue.

Pièges courants

• Les étiquettes de champs semblent non traduites. Elles se trouvent dans la Traduction de chaînes, et non dans la traduction de l’article. Envoyez l’élément Étiquettes du groupe de champs du groupe de champs depuis le tableau de bord (voir Traduire les étiquettes de champs ACF ci-dessus).
• Les valeurs de choix semblent non traduites. Même chose. Envoyez le groupe de champs depuis la section Groupe de champs ACF du tableau de bord afin que les valeurs d’options soient incluses.
• Les lignes du répéteur se désynchronisent. Le champ est probablement réglé sur Copier une fois alors que Copier permettrait de garder les lignes alignées. Ouvrez le groupe de champs > réglez le comportement du champ Répéteur sur Copier.
• La logique conditionnelle se comporte de manière inattendue. Lorsque le champ de contrôle est réglé sur Copier ou Ne pas traduire, le comportement conditionnel suit la valeur de la langue source dans toutes les traductions. Réglez le champ de contrôle sur Traduire si sa valeur doit différer selon la langue.
• Les champs locaux (enregistrés en PHP) ignorent les préférences de traduction définies dans l’interface d’administration. Définissez la clé wpml_cf_preferences dans la définition même du groupe de champs et lancez la synchronisation depuis ACF > Outils. La procédure se trouve dans Définir les préférences pour les champs enregistrés en PHP ou JSON ci-dessus. ACFML 2.2.0 (février 2026) a ajouté une prise en charge complète des champs locaux ; les anciennes versions présentaient des limites à ce niveau.

Hooks de développement pour les cas particuliers

Pour un contrôle programmatique (exclure des champs spécifiques de la traduction, remplacer la préférence par défaut pour un type de champ sur l’ensemble du site, masquer les annotations aux traducteurs ou exclure les chaînes de groupes de champs des tâches de traduction d’articles), ACFML expose deux filtres et quatre constantes. La référence complète, avec des exemples de code, est disponible dans la Référence des hooks et constantes d’ACFML.