# Capacités déclarées par un agent, traduites pour un usage multilingue

> Les étapes pour exposer, via l'Abilities API de WordPress, des descriptions de capacités d'agent traduites selon la langue déclarée par l'appelant.

- Auteur : Clément Hadrot
- Publié le : 2026-05-29
- Mis à jour le : 2026-05-29
- Catégorie : Multilingue
- URL : https://wpmoderne.dev.wordpress-developpement.fr/multilingue/capacites-declarees-agent-traduites-usage-multilingue/

## L’essentiel

- Chaque capacité déclare un libellé traduisible, pas figé en anglais
- La langue de réponse dépend de l'appelant, pas du site par défaut
- Documenter la capacité dans chaque langue supportée, dès sa création

« Abilities are structured, self-descriptive functionalities that a WordPress site can expose. » Cette description, issue de la documentation officielle de l'Abilities API introduite avec WordPress 6.9 en décembre 2025, résume l'idée centrale de ce nouveau système : permettre à un site d'exposer des capacités structurées, consommables aussi bien par des extensions que par des agents automatisés externes.

Sur le site de l'éditeur de logiciels de gestion Ferronex, plusieurs capacités ont été exposées via cette API pour permettre à un agent externe de consulter des statuts de commande ou de déclencher des actions de support. Le site sert une clientèle répartie sur plusieurs pays, et l'équipe voulait que la description de chaque capacité, lue par l'agent appelant avant de l'utiliser, s'affiche dans la langue déclarée par cet appelant plutôt que systématiquement en anglais.

## Étape 1 : déclarer la capacité avec un libellé traduisible

La première étape consiste à enregistrer la capacité avec `wp_register_ability()`, en s'assurant que le libellé et la description exposés à l'appelant passent par les fonctions de traduction standard de WordPress plutôt que d'être écrits en dur dans une seule langue :

```
wp_register_ability( 'ferronex/order-status', array(
    'label'       => __( 'Consulter le statut d\'une commande', 'ferronex' ),
    'description' => __( 'Retourne le statut actuel d\'une commande à partir de son identifiant.', 'ferronex' ),
    'input_schema'  => array(
        'type'       => 'object',
        'properties' => array(
            'order_id' => array( 'type' => 'integer' ),
        ),
    ),
    'execute_callback' => 'ferronex_get_order_status',
) );
```

## Étape 2 : lire la langue déclarée par l'appelant

> L'essentiel à retenir : Chaque capacité déclare un libellé traduisible, pas figé en anglais ; La langue de réponse dépend de l'appelant, pas du site par défaut ; Documenter la capacité dans chaque langue supportée, dès sa création

Un agent appelant transmet généralement sa langue préférée dans l'en-tête de sa requête ou dans un paramètre dédié du protocole utilisé. Cette valeur doit être lue avant la génération de la réponse, puis convertie en une bascule de locale WordPress temporaire, exactement comme pour un appel utilisateur classique :

```
add_filter( 'wp_ability_response', function( $response, $ability_name, $request ) {
    $locale_demandee = $request->get_header( 'X-Requested-Locale' );
    if ( ! $locale_demandee ) {
        return $response;
    }
    switch_to_locale( $locale_demandee );
    $response['label']       = __( 'Consulter le statut d\'une commande', 'ferronex' );
    $response['description'] = __( 'Retourne le statut actuel d\'une commande à partir de son identifiant.', 'ferronex' );
    restore_current_locale();
    return $response;
}, 10, 3 );
```

## Étape 3 : documenter chaque capacité dans toutes les langues supportées

Chaque capacité déclarée doit disposer de sa traduction dans le fichier de traduction du plugin dès sa création, pas ajoutée après coup. Un agent appelant qui reçoit une description dans une langue qu'il ne gère pas mal interprète parfois le schéma d'entrée attendu, ce qui peut se traduire par des appels malformés côté agent.

- Enregistrer chaque capacité avec des libellés passés par les fonctions de traduction
- Lire la locale demandée par l'appelant avant de générer la réponse
- Ajouter la traduction de chaque nouvelle capacité au même moment que sa déclaration

## Étape 4 : vérifier le comportement par défaut sans langue déclarée

Certains appelants ne transmettent aucune préférence de langue. Dans ce cas, la capacité doit répondre dans la langue par défaut du site plutôt que dans une langue arbitraire, un comportement de repli à vérifier explicitement lors des tests plutôt qu'à supposer correct par défaut.

> Une capacité d'agent mal documentée dans la langue de l'appelant se traduit rarement par une erreur explicite : elle se traduit par des appels mal formés, plus difficiles à diagnostiquer après coup.

## Ce que cela change pour les intégrations tierces

Une fois les capacités correctement traduites, les agents externes intégrés au support client de Ferronex ont réduit leurs appels malformés de façon notable dès la première semaine, un effet directement lié à la clarté des descriptions reçues dans leur propre langue plutôt qu'à un changement de leur propre logique interne.

## En résumé

Exposer des capacités traduites via l'Abilities API demande peu de code supplémentaire : des libellés passés par les fonctions de traduction habituelles, une lecture de la locale demandée par l'appelant, et une traduction systématique dès la création de chaque capacité. Ce soin, souvent négligé au profit de la seule logique fonctionnelle, conditionne pourtant la qualité des appels reçus des agents externes.