# Brancher l’API DeepL sur un workflow de traduction WordPress fait maison

> Plutôt que dépendre entièrement d'un plugin premium, brancher l'API DeepL directement dans un développement sur mesure offre un contrôle total. Recette commentée.

- Auteur : Clément Hadrot
- Publié le : 2023-05-30
- Mis à jour le : 2023-05-30
- Catégorie : Multilingue
- URL : https://wpmoderne.dev.wordpress-developpement.fr/multilingue/deepl-api-workflow-traduction-recette/

## L’essentiel

- L'API DeepL distingue clairement offre gratuite et offre Pro par quota
- Une file d'attente évite de bloquer l'interface d'administration
- La relecture humaine reste indispensable avant publication

Un client avait un besoin précis que ni WPML ni Polylang ne couvraient nativement de façon satisfaisante : pré-traduire automatiquement un flux de contenu généré par une source externe (un catalogue produit synchronisé via un flux XML) avant intégration dans WordPress, sans passer par l'interface d'administration classique. La solution retenue : brancher directement l'API DeepL dans un script de traitement, en amont de l'import WordPress. Cette recette détaille la mise en œuvre, du côté sécurisé de la clé API jusqu'à la file d'attente qui évite de saturer les quotas.

Nous ne traitons pas ici de l'utilisation de DeepL via un plugin comme WPML (qui propose sa propre intégration native), mais d'un appel direct à l'API, utile pour des besoins sur mesure : traduction en tâche de fond, traitement par lot, ou intégration dans un pipeline d'import de données externe.

## Obtenir et sécuriser une clé API

DeepL propose deux offres d'API distinctes : **DeepL API Free**, avec un quota mensuel de caractères traduits, et **DeepL API Pro**, facturée au volume sans limite fixe, avec une garantie contractuelle de non-conservation des textes traduits à des fins d'entraînement — un point souvent déterminant pour des clients soumis à des clauses de confidentialité strictes sur leurs contenus.

La clé API ne doit jamais être codée en dur dans un fichier de thème ou d'extension versionné. Elle est stockée soit comme constante dans `wp-config.php` (en dehors du dépôt Git), soit via une option chiffrée en base, accessible uniquement aux administrateurs :

```
// wp-config.php
define( 'DEEPL_API_KEY', 'votre-cle-api-ici' );
```

## Un appel de traduction basique

L'API DeepL s'utilise via une simple requête HTTP, ce qui permet de s'appuyer directement sur la fonction native `wp_remote_post()` de WordPress, sans dépendance externe supplémentaire :

```
<?php
function traduire_avec_deepl( $texte, $langue_cible = 'FR' ) {
    $reponse = wp_remote_post( 'https://api-free.deepl.com/v2/translate', array(
        'headers' => array(
            'Authorization' => 'DeepL-Auth-Key ' . DEEPL_API_KEY,
        ),
        'body' => array(
            'text'        => $texte,
            'target_lang' => $langue_cible,
        ),
        'timeout' => 15,
    ) );

    if ( is_wp_error( $reponse ) ) {
        return new WP_Error( 'deepl_erreur', $reponse->get_error_message() );
    }

    $corps = json_decode( wp_remote_retrieve_body( $reponse ), true );
    return $corps['translations'][0]['text'] ?? false;
}
```

Le point d'accès diffère selon l'offre souscrite : `api-free.deepl.com` pour l'offre gratuite, `api.deepl.com` pour l'offre Pro. Une erreur fréquente de débutant consiste à utiliser le mauvais point d'accès selon la clé fournie, ce qui renvoie une erreur d'authentification trompeuse laissant croire à une clé invalide.

> L'essentiel à retenir : L'API DeepL distingue clairement offre gratuite et offre Pro par quota ; Une file d'attente évite de bloquer l'interface d'administration ; La relecture humaine reste indispensable avant publication

## Mettre en file d'attente plutôt que traduire en direct

Traduire en temps réel au moment de la publication d'un contenu bloque l'interface d'administration le temps de la réponse de l'API, ce qui devient inacceptable dès que le volume de texte grandit. La bonne pratique consiste à déléguer la traduction à une tâche planifiée, via l'API Cron de WordPress ou une exécution WP-CLI programmée en dehors des heures de pointe :

```
<?php
add_action( 'mon_import_catalogue_traduction', function( $post_id ) {
    $texte_source = get_post_field( 'post_content', $post_id );
    $traduction = traduire_avec_deepl( $texte_source, 'EN' );

    if ( $traduction ) {
        update_post_meta( $post_id, '_traduction_en_brouillon', $traduction );
        update_post_meta( $post_id, '_traduction_statut', 'a_relire' );
    }
} );

wp_schedule_single_event( time() + 30, 'mon_import_catalogue_traduction', array( $post_id ) );
```

Le résultat n'écrase jamais directement le contenu publié : il est stocké comme brouillon en attente de relecture, avec un statut explicite (`a_relire`), avant toute publication effective. C'est un choix de conception délibéré, détaillé dans la section suivante.

## Pourquoi la relecture humaine reste non négociable

DeepL produit des traductions globalement fluides, mais reste sujet à des erreurs contextuelles typiques des systèmes de traduction automatique : contresens sur des termes techniques propres au métier du client, perte du ton de marque (une voix décontractée traduite dans un registre trop formel), ou traduction littérale d'expressions idiomatiques qui n'ont pas d'équivalent naturel dans la langue cible.

Publier une traduction automatique sans relecture, même sur un contenu jugé secondaire (une fiche produit parmi des centaines), expose à un risque de crédibilité disproportionné par rapport au gain de temps réalisé : un seul contresens visible dans un email ou une page produit suffit à entamer la confiance d'un visiteur dans le sérieux du site.

> Sur ce projet, nous avons imposé une règle simple dans le workflow : aucun contenu traduit automatiquement ne passe au statut « publié » sans qu'un champ de méta « relu_par » contienne l'identifiant d'un utilisateur humain. Une contrainte technique simple, mais qui a évité plusieurs publications hâtives.

## Gérer les quotas et les erreurs de dépassement

L'API DeepL retourne un code HTTP `456` spécifique lorsque le quota mensuel est dépassé (offre gratuite) ou lorsque la limite contractuelle est atteinte (offre Pro selon le plan souscrit). Un script de production robuste doit intercepter ce code explicitement et interrompre la file d'attente proprement, avec une notification à l'équipe plutôt qu'un échec silencieux répété à chaque tentative :

```
<?php
$code_http = wp_remote_retrieve_response_code( $reponse );
if ( 456 === (int) $code_http ) {
    // Quota dépassé : interrompre la file et notifier l'équipe
    wp_mail( 'equipe@exemple.fr', 'Quota DeepL dépassé', 'La file de traduction est en pause.' );
    return false;
}
```

## En résumé

Brancher l'API DeepL directement dans un développement sur mesure offre un contrôle précis sur le workflow de traduction, particulièrement utile pour des besoins qui sortent du cadre standard d'un plugin multilingue. La discipline technique — clé API sécurisée, file d'attente asynchrone, gestion explicite des quotas — n'a de sens que combinée à une discipline éditoriale tout aussi stricte : aucune traduction automatique ne devrait atteindre un visiteur sans être passée par un regard humain.