← Retour au blog
Terminal window showing a Composer install command for the PolyLingo PHP SDK alongside a short PHP translate call and its JSON output.

Traduire du contenu structuré depuis PHP avec le SDK PolyLingo

By Robert M

Traduire du contenu structuré depuis PHP avec le SDK PolyLingo

Le SDK PolyLingo PHP est désormais disponible sur Packagist. Installez-le avec Composer, fournissez-lui une chaîne de texte brut, Markdown, JSON ou HTML, et obtenez des traductions dans toutes les langues dont vous avez besoin — sans écrire de requêtes HTTP brutes ni craindre que votre structure soit altérée en transit.

Cet article couvre l'installation, l'authentification et l'ensemble des fonctionnalités du SDK : traduction synchrone, requêtes par lot, travaux asynchrones et gestion des erreurs.

Installation

Nécessite PHP 7.4 ou supérieur. Installez via Composer :

composer require usepolylingo/polylingo

Le SDK dépend de guzzlehttp/guzzle ^7.8 et psr/http-client ^1.0. Les deux sont installés automatiquement.

Configuration du client

Créez une instance unique de PolyLingo et réutilisez-la dans votre application. La seule option requise est votre clé API :

<?php
use PolyLingo\PolyLingo;

$client = new PolyLingo([
    'apiKey' => getenv('POLYLINGO_API_KEY'),
]);

Stockez votre clé API dans une variable d'environnement. Ne la codez jamais en dur ni ne la commettez dans le contrôle de version.

Deux paramètres optionnels à connaître :

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // par défaut, à modifier pour des instances auto-hébergées
    'timeout' => 120_000,                           // en millisecondes, défaut 120000 (2 minutes)
]);

Traduction de contenu

Texte brut, Markdown, JSON ou HTML

Passez votre contenu et un tableau de codes de langues cibles à translate(). Le champ format indique au SDK le type de contenu :

$result = $client->translate([
    'content' => '# Hello',
    'targets' => ['es', 'fr', 'de'],
    'format'  => 'markdown',
]);

$es     = $result['translations']['es'];
$tokens = $result['usage']['total_tokens'];

L'option format accepte plain, markdown, json ou html. Si vous l'omettez, l'API détecte automatiquement le format à partir du contenu. Vous pouvez aussi fournir un indice de langue source et une valeur model parmi standard (par défaut) ou advanced.

La préservation du format est le comportement clé ici. Pour le contenu json, seules les valeurs de chaîne sont traduites. Les clés, la structure imbriquée, les tableaux et les types non-chaînes sont renvoyés exactement comme vous les avez envoyés. Pour le markdown, les titres restent des titres, les blocs de code sont laissés tels quels, et les URL des liens ne sont pas modifiées. Pour le html, les balises et attributs sont préservés et seuls les nœuds de texte sont traduits.

Traduction d'un fichier de locale JSON

Un cas d'usage courant est la traduction d'un fichier de locale. Envoyez l'objet complet sous forme de chaîne JSON :

$source = json_decode(file_get_contents('messages/en.json'), true);

$result = $client->translate([
    'content' => json_encode($source),
    'format'  => 'json',
    'targets' => ['de', 'fr', 'ja'],
]);

foreach (['de', 'fr', 'ja'] as $locale) {
    $translated = json_decode($result['translations'][$locale], true);
    file_put_contents(
        "messages/{$locale}.json",
        json_encode($translated, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n"
    );
}

Une seule requête gère les trois locales. Les clés restent intactes dans chaque fichier de sortie.

Requêtes par lot

Utilisez batch() lorsque vous avez plusieurs éléments de contenu séparés à traduire. Vous pouvez envoyer jusqu'à 100 éléments dans une seule requête, chacun avec son propre id et un format optionnel :

$batch = $client->batch([
    'items' => [
        ['id' => 'hero_title',    'content' => 'Welcome back',              'format' => 'plain'],
        ['id' => 'hero_subtitle', 'content' => 'Here is what is new today', 'format' => 'plain'],
        ['id' => 'cta',           'content' => 'Get started',               'format' => 'plain'],
    ],
    'targets' => ['es', 'fr'],
]);

foreach ($batch['results'] as $row) {
    echo $row['id'] . ': ' . $row['translations']['es'] . "\n";
}

Tous les éléments partagent le même tableau targets. La réponse conserve l'id que vous avez passé pour chaque élément, vous permettant de faire correspondre les résultats à vos données originales sans dépendre de l'ordre.

Travaux asynchrones

Pour les traductions longues (documents volumineux, nombreuses cibles, ou les deux), l'API jobs accepte une requête, retourne immédiatement un job_id, et vous permet de sonder le résultat. Le SDK gère cela de deux façons.

Mettre en file et sonder manuellement

$accepted = $client->jobs->create([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de', 'ja', 'zh'],
    'format'  => 'markdown',
]);

$jobId = $accepted['job_id'];

// Sondez jusqu'à ce que le travail atteigne un statut terminal
do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

if ($state['status'] === 'complete') {
    $translations = $state['translations'];
}

Un appel qui sonde jusqu'à la fin

Si vous n'avez pas besoin de contrôle manuel, jobs->translate() gère la boucle de sondage pour vous :

$done = $client->jobs->translate([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de'],
    'format'  => 'markdown',

    // Surcharges optionnelles (valeurs par défaut affichées) :
    // 'pollInterval' => 5000,       // ms entre les sondages, défaut 5000
    // 'timeout'      => 1_200_000,  // budget total d'attente, défaut 20 minutes
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Position dans la file : {$queuePosition}\n";
    // },
]);

$translations = $done['translations'];
$usage        = $done['usage'];

Le callback onProgress est appelé à chaque sondage avec la position actuelle dans la file si l'API la retourne, ou null sinon. Utilisez-le pour journaliser la progression ou mettre à jour une interface utilisateur.

Points de terminaison utilitaires

Trois points de terminaison légers ne nécessitent aucun paramètre autre que l'authentification :

$health = $client->health();
// ['status' => 'ok', 'timestamp' => '...']

$langs = $client->languages();
// ['languages' => [['code' => 'en', 'name' => 'English', 'rtl' => false], ...]]

$usage = $client->usage();
// ['usage' => ['tokens_used' => 12000, 'tokens_remaining' => 88000, ...]]

GET /health et GET /languages ne nécessitent pas de clé API. GET /usage retourne la consommation de jetons pour le mois calendaire en cours pour le compte authentifié.

Gestion des erreurs

Toutes les erreurs du SDK étendent PolyLingo\Errors\PolyLingoException. Attrapez les sous-types spécifiques que vous souhaitez gérer différemment :

use PolyLingo\Errors\AuthException;
use PolyLingo\Errors\JobFailedException;
use PolyLingo\Errors\PolyLingoException;
use PolyLingo\Errors\RateLimitException;

try {
    $result = $client->translate([
        'content' => '# Hello',
        'targets' => ['es'],
        'format'  => 'markdown',
    ]);
} catch (AuthException $e) {
    // HTTP 401 — clé API invalide, manquante ou révoquée
} catch (RateLimitException $e) {
    // HTTP 429 — limite par minute atteinte
    $retryAfter = $e->getRetryAfter(); // int|null en secondes
} catch (JobFailedException $e) {
    // Travail asynchrone atteint un statut terminal échoué
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Toutes les autres erreurs API
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // ex. "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() retourne le nombre de secondes à attendre avant de réessayer si l'API inclut cet en-tête, ou null sinon. JobFailedException::getJobId() vous donne l'ID du travail échoué pour que vous puissiez le journaliser ou l'afficher à l'utilisateur.

Référence rapide

MéthodePoint d'accèsAuth requise
$client->health()GET /healthNon
$client->languages()GET /languagesNon
$client->translate()POST /translateOui
$client->batch()POST /translate/batchOui
$client->usage()GET /usageOui
$client->jobs->create()POST /jobsOui
$client->jobs->get($id)GET /jobs/:idOui
$client->jobs->translate()POST /jobs + sondageOui

Commencer

Le SDK est sur Packagist à usepolylingo/polylingo. La documentation complète de l'API est disponible sur usepolylingo.com/docs.

Le niveau gratuit inclut 50 000 jetons par mois. Aucune carte de crédit requise.

composer require usepolylingo/polylingo

Obtenez votre clé API