Référence complète de l'API : developer.universally.com contient la spécification en direct pour l'API Traducteur et l'API Plateforme, avec tous les champs, codes d'état et exemples de réponses. Cette page couvre ce qu'il faut savoir à ce sujet.
Envoyez le HTML d'une page, recevez le même HTML avec son texte traduit. C'est le point de terminaison qu'utilise le plugin WordPress, et celui à utiliser pour toute plateforme capable de rendre une page côté serveur.
Point de terminaison
POST https://translator.universally.com/v1/translate/html
X-API-Key: your_api_key_here
Content-Type: application/json
Demande
{
"html": "<html>...</html>",
"targetLanguage": "es",
"sourceUrl": "https://example.com/pricing/",
"parserMode": "auto"
}
| Champ | Requis | Remarques |
|---|---|---|
html |
oui | Le document complet, ou un fragment. Ne doit pas être vide. |
langueCible |
oui | L'un des codes de variante configurés du projet, tels que es, es-419 ou pt-br. Un code régional tel que es-mx est rejeté |
urlSource |
oui | Doit être une URL valide, et son domaine doit correspondre au domaine du projet |
modeAnalyseur |
no | auto ou classic. Par défaut auto. |
sourceUrl n'est pas une décoration. Il identifie quelle page est traduite afin que le résultat puisse être stocké et réutilisé, et il est vérifié par rapport au domaine de votre projet. Une non-concordance renvoie TRANSLATION_SOURCE_URL_DOMAIN_MISMATCH.
Réponse
{
"success": true,
"data": {
"translatedHtml": "<html>...</html>",
"metadata": {
"siteId": "site_123",
"siteDomain": "example.com",
"sourceLanguage": "en",
"targetLanguage": "es",
"sourceUrl": "https://example.com/pricing/",
"stringsExtracted": 142,
"stringsTranslated": 142,
"limitReached": false,
"skippedStrings": 0
}
},
"code": "DATA_FETCHED"
}
Servez translatedHtml au visiteur. Les métadonnées sont pour votre propre journalisation et valent la peine d'être enregistrées :
limitReached est true lorsque le projet était déjà à sa limite de mots ou au-delà lorsque la requête est arrivée. Vous obtenez toujours un HTML valide et un code 200, avec le texte dans la langue source partout où une nouvelle traduction aurait été nécessaire. Voir Limites d'utilisation.
skippedStrings compte ce qui a été laissé sans traduction. C'est le seul signal de saut : il est défini pour la limite de mots et rien d'autre. Les règles d'exclusion n'apparaissent pas ici, car le contenu exclu est supprimé avant que quoi que ce soit ne soit extrait. Une page entièrement exclue revient avec tous les compteurs à zéro.
stringsExtracted par rapport à stringsTranslated diffèrent régulièrement, et un écart en soi ne signifie rien de mal. Le texte apparaissant à plusieurs endroits (un <title> qui est aussi un og:title et un headline JSON-LD), les chaînes qui sont ignorées comme intraduisibles (une URL nue, une adresse e-mail, un nombre, un seul caractère), et tout ce que la limite de mots a ignoré en sont la cause.
targetLanguage fait écho à la variante que vous avez envoyée, normalisée en minuscules. Elle est comparée exactement aux variantes configurées du projet plutôt que résolue à partir d'une région, c'est pourquoi es-mx renvoie TRANSLATION_TARGET_LANGUAGE_NOT_ALLOWED tandis que es-419 fonctionne. Voir Variantes linguistiques et ciblage régional.
Requêtes compressées
Définissez Content-Encoding: gzip et envoyez le corps compressé. La limite de taille compte les octets que vous envoyez, donc la compression permet de faire passer un grand document.
Limites
Le corps de la requête ne peut pas dépasser 5 Mo tels qu'envoyés, ce qui correspond à la taille compressée lorsque vous utilisez gzip. Au-delà, cela renvoie REQUEST_TOO_LARGE avec le statut 413. Voir Erreurs et limites de l'API.
Mise en cache de votre côté
La réponse est stockée de notre côté, donc une requête répétée pour la même page et la même langue est rapide et ne dépense plus de mots. C'est toujours un aller-retour réseau.
Mettez en cache le HTML traduit dans votre propre couche, comme le fait le plugin WordPress. C'est la différence entre une page rapide et une page assez rapide. Voir Performance et vitesse de page.
Lorsqu'une page est exclue
Si le chemin correspond à une règle Exclure les pages, le point de terminaison renvoie avec succès le HTML d'origine plutôt qu'une erreur. Vérifiez les métadonnées si vous avez besoin de distinguer les deux. Voir Exclure les pages.