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

Champs de contenu

Champs de choix

Champs jQuery

Champs de mise en page

Champs relationnels

Pour un champ de type Lien, la traduction couvre le texte du lien et l’URL. Lorsque l’URL pointe vers une page de votre site et que vous ne la modifiez pas, WPML affiche la page dans la langue du visiteur.

Champs d’URL et de lien

À partir d’ACFML 5.0, les champs d’URL et de lien utilisent la préférence Traduire par défaut.

Relations bidirectionnelles

Depuis ACF 6.2, les champs Relation, Objet de publication, Taxonomie et Utilisateur peuvent être bidirectionnels. Lorsque vous sélectionnez une cible dans le champ, ACF ajoute votre article au champ associé de la cible. Par exemple, le livre Dune définit son champ Auteur sur Frank Herbert. ACF ajoute ensuite Dune au champ Livres de Frank Herbert.

ACFML conserve la paire dans chaque langue :

• Lorsque WPML copie le champ vers une traduction, ACFML fait pointer le champ vers la cible dans la même langue. Ensuite, ACFML ajoute la traduction au champ apparié de cette cible. Le Dune espagnol affiche le Frank Herbert espagnol, et le Frank Herbert espagnol liste le Dune espagnol.
• Lorsque le champ utilise l’option Copier et que vous modifiez la cible dans l’article d’origine, WPML met à jour la traduction. ACFML ajoute la traduction à la nouvelle cible dans cette langue et la supprime de l’ancienne cible.
• ACFML modifie uniquement les cibles dans la langue de la traduction. Les articles dans la langue d’origine conservent leur propre paire.
• Lorsque la cible n’a pas encore de traduction, la traduction pointe vers la cible d’origine, et ACFML ne modifie pas la cible d’origine. Lorsque vous traduisez la cible par la suite, ACFML fait pointer le champ vers la nouvelle traduction et ajoute l’article à son champ apparié. Le champ liste la cible une seule fois.
• Les utilisateurs n’ont pas de traductions, ACFML n’ajoute donc pas de traductions au champ apparié d’un utilisateur. Ce champ conserve l’article d’origine. Dans une autre langue, ACFML affiche la traduction de cet article, à moins que le champ n’utilise l’option Copier.

Cela fonctionne pour les préférences Copier et Copier une fois, qui sont les préférences recommandées pour ces types de champs. Cela fonctionne également lorsque vous dupliquez un article avec WPML.

Traduire les blocs ACF

Par défaut, les blocs ACF enregistrent les valeurs de leurs champs à l’intérieur du bloc, dans le contenu de l’article, et non en tant que champs personnalisés. ACFML envoie ces valeurs pour traduction en même temps que le reste de l’article, dans la même tâche de traduction.

• Le bloc utilise l’option de traduction et les préférences de champ du groupe de champs dont la règle d’emplacement est ce bloc.
• ACFML envoie uniquement les champs qui utilisent l’option Traduire. Les champs qui utilisent les options Copier, Copier une fois ou Ne pas traduire conservent la valeur du bloc d’origine.
• Les champs Répéteur et Contenu flexible à l’intérieur d’un bloc se traduisent également, même lorsqu’ils sont imbriqués. Chaque sous-champ utilise sa propre préférence de traduction.
• Un bloc avec "usePostMeta": true dans la section acf de son block.json enregistre ses valeurs en tant que champs personnalisés de l’article, et non dans le bloc. Ces valeurs se traduisent comme n’importe quel autre champ personnalisé de l’article, avec l’option de traduction et les préférences de champ du groupe de champs.
• Lorsque vous modifiez une préférence de traduction dans un groupe de champs que vous utilisez sur des blocs, WPML vous demande si vous souhaitez mettre à jour les traductions existantes. Si vous confirmez, WPML marque les traductions de ces articles comme nécessitant une mise à jour. Envoyez-les à nouveau en traduction pour appliquer la modification. Une modification vers Ne pas traduire ne les marque pas.

Champs déclarés dans block.json

Depuis ACF 6.8.1, un bloc peut déclarer ses champs dans son fichier block.json, dans acf.fields. ACF crée un groupe de champs pour ces champs, et vous ne pouvez pas modifier ce groupe de champs dans l’interface d’administration. ACFML lui attribue l’option Même contenu dans chaque langue, traduit et la préférence recommandée pour chaque type de champ, comme un groupe de champs enregistré en PHP.

Pour utiliser une autre option pour l’ensemble du groupe, ajoutez acfml_field_group_mode à la section acf de block.json, ou à acf_register_block_type(). Les valeurs acceptées sont translation (Même contenu dans chaque langue, traduit), localization (Chaque langue a son propre contenu) et advanced (Expert). ACFML ignore toute autre valeur.

{
    "name": "acme/event-card",
    "title": "Event Card",
    "acf": {
        "mode": "preview",
        "acfml_field_group_mode": "localization",
        "fields": [ ... ]
    }
}

Pour définir la préférence d’un champ, ajoutez wpml_cf_preferences à ce champ. ACFML conserve cette préférence avec chaque option. Avec Expert, seuls les champs qui déclarent wpml_cf_preferences obtiennent une préférence.

Lorsque block.json n’indique pas d’option, ACFML stocke l’option qu’il attribue au groupe la première fois qu’il le rencontre, et la conserve par la suite. Sur les sites qui utilisaient ces blocs avec une ancienne version d’ACFML, l’option stockée est Expert.

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

Les groupes de champs ACF enregistrés en PHP (avec acf_add_local_field_group()) ou via la fonctionnalité Local JSON d’ACF ne prennent pas les préférences de traduction depuis les écrans de l’interface d'administration, car l’interface d'administration ne les gère pas. Définissez les préférences au même endroit où vous enregistrez les champs.

Pour définir l’option de traduction du groupe de champs, ajoutez la clé acfml_field_group_mode à la définition, avec translation, localization ou advanced (Expert). Lorsque la définition ne définit aucune option de traduction, ACFML donne au groupe de champs l’option Même contenu dans chaque langue, traduit la première fois qu’il voit le groupe. ACFML stocke cette option et la conserve par la suite. Les groupes de champs qui existent avant la mise à jour de votre site vers WPML 5.2 conservent Expert.

Pour chaque champ dans 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 entre 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’à Translate ACF Local JSON and PHP-Registered Fields.
3. Dans Sync Translation Preferences for Local Fields, sélectionnez Sync once now et cliquez sur Appliquer.

WPML lit les préférences de vos définitions de champs et les stocke. Sync once now s’exécute une seule fois. Si vous modifiez souvent les définitions, sélectionnez plutôt Sync on every request (may affect performance). Cette option exécute la synchronisation à chaque requête de l’interface d'administration.

Si vous utilisez la fonctionnalité Local JSON d’ACF pour partager des groupes de champs entre des sites, ACFML écrit automatiquement les préférences de traduction dans les fichiers JSON. Exportez un fichier JSON 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.

Les groupes de champs qu’ACF crée avec la commande WP-CLI wp acf json import, ou via son API Abilities pour les outils d’IA, sont stockés dans la base de données. ACFML leur donne l’option Même contenu dans chaque langue, traduit et la préférence recommandée pour chaque type de champ. Lorsque le JSON importé possède déjà une clé acfml_field_group_mode, ACFML utilise cette option à la place.

Groupes de champs dans les fichiers Local JSON

ACF charge les groupes de champs du dossier acf-json très tôt dans chaque requête. À partir de WPML 5.2, ACFML lit ces groupes de champs en même temps. Ainsi, lorsque vous synchronisez les préférences de traduction, la synchronisation couvre également les groupes de champs JSON. WPML utilise ensuite les préférences des fichiers JSON.

Dans le fichier JSON, ajoutez wpml_cf_preferences à chaque champ, avec les mêmes valeurs qu’en PHP. Cette clé définit la préférence de chaque champ, quelle que soit l’option de traduction du groupe de champs. L’exemple utilise Expert :

{
    "key": "group_event",
    "title": "Event",
    "acfml_field_group_mode": "advanced",
    "fields": [
        {
            "key": "field_event_title",
            "label": "Event Title",
            "name": "event_title",
            "type": "text",
            "wpml_cf_preferences": 2
        },
        {
            "key": "field_event_price",
            "label": "Price",
            "name": "event_price",
            "type": "number",
            "wpml_cf_preferences": 1
        }
    ]
}

Pour envoyer les préférences et les libellés des groupes de champs JSON à WPML :

1. Accédez à ACF → Outils.
2. Faites défiler jusqu’à Translate ACF Local JSON and PHP-Registered Fields.
3. Dans Sync Translation Preferences for Local Fields, sélectionnez Sync once now ou Sync on every request (may affect performance).
4. Dans Register Labels for Translation, sélectionnez Register labels now.
5. Cliquez sur Appliquer.

Pour vérifier le résultat, accédez à WPML → Paramètres et trouvez les champs dans Traduction des champs personnalisés. Chaque champ affiche la préférence du fichier JSON. ACFML enregistre également les libellés des groupes de champs, des types de publication, des taxonomies et des pages d'options qui n’existent que dans le code : dans le dossier acf-json ou enregistrés en PHP. Traduisez-les comme les libellés de n’importe quel autre groupe de champs (voir Traduire les libellés des champs ACF ci-dessous).

Traduire les libellés des champs ACF

Les libellés des champs ACF sont les noms qui identifient chaque champ personnalisé dans l’éditeur WordPress et sur l’interface publique (par exemple, Numéro de téléphone, Adresse). Ils se traduisent séparément des valeurs des champs, et ils se trouvent dans WPML Traduction de chaînes, et non dans la tâche de traduction de l’article.

Pour envoyer les libellés des champs à la traduction :

1. Ouvrez WPML → Traductions → Tableau de bord.
2. Développez la section ACF Field Group.
3. Sélectionnez l’élément Field Group Labels 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 libellés traduits apparaissent automatiquement sur l’interface publique une fois la traduction terminée.

Arrêtez de traduire les libellés de champ

Par défaut, la tâche de traduction d'un article n'inclut pas les libellés de champ. Vous les traduisez uniquement lorsque vous envoyez l'élément Libellés de groupe de champs depuis le tableau de bord. Si vous ne l'envoyez pas, ACF affiche les libellés d'origine. Pour afficher les libellés d'origine même lorsque des traductions existent, utilisez le filtre acfml_should_translate_acf_entity et renvoyez false pour les champs ou les groupes de champs que vous souhaitez ignorer. La référence des hooks et constantes ACFML contient un exemple.

Traduisez les choix de champs ACF

Les champs de choix (Sélection, Case à cocher, Bouton radio, Groupe de boutons) comportent leurs propres libellés d'option (par exemple, Petit / Moyen / Grand). Ceux-ci se trouvent également aux côtés des libellés de champ plutôt qu'à l'intérieur de 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.

Traduisez 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) se traduisent en tant que type d'objet propre, 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.

L'option de traduction du groupe de champs sur la page d'options détermine ce qui arrive à chaque champ :

• Les champs qui utilisent Traduire vont dans l'élément Options ACF que vous envoyez depuis le tableau de bord de traduction. Lorsque la traduction est terminée, ACFML écrit les valeurs sur la page d'options de cette langue. Les champs Répéteur et Contenu flexible obtiennent les mêmes lignes que l'original.
• Les champs qui utilisent Copier obtiennent la valeur de l'original dans chaque langue. Lorsque vous enregistrez l'original, ACFML met à jour les autres langues.
• Les champs qui utilisent Copier une fois commencent comme une copie de l'original. Ensuite, vous les modifiez sur la page d'options de chaque langue.

Utilisez Chaque langue a son propre contenu lorsque les options diffèrent selon la langue. Par exemple, une page d'options répertorie trois agents commerciaux en anglais et deux en espagnol. Pour choisir l'option, modifiez le groupe de champs, comme pour n'importe quel autre groupe de champs.

Pour modifier une traduction terminée, accédez à WPML → Traductions → Travaux de traduction et cliquez sur Modifier sur la tâche Options ACF. Vous pouvez également modifier les valeurs traduites dans WPML → Traduction de chaînes. Lorsque vous y enregistrez une traduction, ACFML l'écrit sur la page d'options de cette langue.

Lorsque vous modifiez la langue par défaut du site, les valeurs existantes de la page d'options restent dans la langue dans laquelle vous les avez écrites. ACF lit les mêmes valeurs qu'avant la modification.

Dans le code, get_field( 'my_field', 'option' ) renvoie la valeur de la langue actuelle. Après do_action( 'wpml_switch_language', 'fr' ), il renvoie la valeur en français. Cela fonctionne également pour les pages d'options avec un post_id personnalisé.

Problèmes fréquents

• Les libellés de champ semblent non traduits. Ils se trouvent dans la Traduction de chaînes, et non dans la traduction de l'article. Envoyez l'élément Libellés de groupe de champs du groupe de champs depuis le tableau de bord (voir Traduire les libellés de champ ACF ci-dessus).
• Les valeurs de choix semblent non traduites. Même principe. Envoyez le groupe de champs depuis la section Groupe de champs ACF du tableau de bord afin que les valeurs d'option soient incluses.
• Les lignes du répéteur se désynchronisent. Le groupe de champs utilise probablement le mode Expert. Modifiez l'article d'origine, sélectionnez Conserver les sous-champs répéteurs et flexibles dans le même ordre que la langue par défaut dans la boîte Synchroniser les traductions ACFML, puis mettez à jour l'article. Vous pouvez également basculer le groupe de champs sur Même contenu dans chaque langue, traduit.
• La logique conditionnelle se comporte de manière inattendue. Lorsque le champ de contrôle est défini sur Copier ou Ne pas traduire, le comportement conditionnel suit la valeur de la langue source dans toutes les traductions. Définissez 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 synchronisez 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.

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 groupe de champs des tâches de traduction d'articles), ACFML dispose de deux filtres et de quatre constantes. La référence complète avec des exemples de code se trouve dans la référence des hooks et constantes ACFML.