Aperçu de l'API REST

Universally expose une API REST pour traduire le contenu web en plus de 110 langues. L'API est indépendante de la plateforme : tout système capable d'effectuer une requête HTTPS peut envoyer du contenu et recevoir des traductions. Le plugin WordPress officiel est construit sur cette même API, mais rien ici n'est spécifique à WordPress.

Utilisez l'API lorsque vous souhaitez intégrer la traduction directement dans votre propre pile : un CMS personnalisé, un frontend headless, un worker edge, une application mobile ou web, ou tout autre endroit où le plugin ne peut pas accéder.

Mais comme nous ne prenons officiellement en charge que l'intégration WordPress, il s'agit plutôt d'un aperçu général de l'API qui devrait permettre d'étendre le plugin.

Deux services

L'API est répartie sur deux hôtes distincts. Chacun possède un ensemble d'endpoints distincts, donc l'hôte vous indique la capacité que vous appelez.

Service de traduction

https://translator.universally.com

C'est ici que toute la traduction se déroule. La plupart des intégrations n'appellent que ce service.

Méthode	Point de terminaison	Description
POST	/v1/translate/html	Traduire un document HTML complet
POST	/v1/translate/strings	Traduire un tableau de chaînes de caractères (URL non requise)
POST	/v1/translate	Détecte automatiquement le HTML ou les chaînes de caractères à partir du corps de la requête
GET	/health	Vérification de l'état (pas d'authentification)

Service API

https://api.universally.com

Ce service fournit des données de référence au niveau du compte. Vous n'en avez pas besoin pour traduire ; il prend en charge la configuration et la sélection de la langue.

Ceci est actuellement très limité pour un usage public.

Authentification en bref

Chaque requête est authentifiée avec une seule clé API envoyée dans l'en-tête X-API-Key. Votre clé est une chaîne de 64 caractères délivrée par site depuis votre tableau de bord Universally, et la même clé fonctionne sur les deux services. Comme la clé peut dépenser votre quota de traduction, gardez-la côté serveur.

X-API-Key: your_api_key_here
Content-Type: application/json

Enveloppe de réponse

Chaque endpoint renvoie la même enveloppe JSON, que la requête réussisse ou échoue :

{
  "success": true,
  "data": { },
  "message": "Human-readable message or null",
  "code": "MACHINE_READABLE_CODE"
}

• success est true pour les réponses 2xx et false pour les erreurs.
• data contient la charge utile en cas de succès et est null en cas d'erreur.
• code est un identifiant stable et lisible par machine sur lequel vous pouvez baser votre logique. Préférez-le à l'analyse de message.

HTML ou chaînes de caractères : quel endpoint dois-je utiliser ?

Le traducteur offre deux façons de traduire, en fonction de la forme de votre contenu.

Utilisez /v1/translate/html lorsque vous avez une page rendue. Vous envoyez un document HTML complet avec son URL canonique. Universally extrait chaque chaîne de caractères traduisible, y compris le texte du corps, les balises meta, les données Open Graph, les données structurées, le texte alternatif des images et les attributs des formulaires, les traduit, localise les liens et renvoie le HTML réécrit. C'est le bon choix pour les pages rendues côté serveur et les intégrations edge.

Utilisez /v1/translate/strings lorsque vous avez des morceaux de texte discrets. Vous envoyez un tableau de chaînes de caractères et recevez une carte du texte original au texte traduit. Aucune URL n'est requise, c'est donc le bon choix pour le contenu qui n'est pas lié à une page : contenu dynamique chargé via AJAX, texte généré par l'utilisateur tel que les commentaires et les avis, contenu d'application, notifications push, ou tout fragment que votre pipeline de rendu produit à la volée.

Si vous n'êtes pas sûr, envoyez la requête à /v1/translate et Universally l'enverra au bon gestionnaire en fonction du corps que vous fournissez.

Exemples

Les deux méthodes de traduction résident dans le service Translator et s'authentifient avec votre clé d'API dans l'en-tête X-API-Key.

Traduire du HTML

Envoyez une page rendue et son URL canonique ; recevez le document traduit en retour.

curl -X POST https://translator.universally.com/v1/translate/html \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<!DOCTYPE html><html><head><title>Welcome</title></head><body><h1>Hello world</h1></body></html>",
    "targetLanguage": "fr",
    "sourceUrl": "https://example.com/welcome"
  }'

Réponse :

{
  "success": true,
  "data": {
    "translatedHtml": "<!DOCTYPE html><html lang=\"fr\"><head><title>Bienvenue</title></head><body><h1>Bonjour le monde</h1></body></html>",
    "metadata": {
      "siteId": "site_123",
      "siteDomain": "example.com",
      "sourceLanguage": "en-us",
      "targetLanguage": "fr",
      "sourceUrl": "https://example.com/welcome/",
      "stringsExtracted": 2,
      "stringsTranslated": 2,
      "limitReached": false,
      "skippedStrings": 0
    }
  },
  "message": "Data retrieved successfully.",
  "code": "DATA_FETCHED"
}

Traduire des chaînes

Envoyez un tableau de chaînes ; recevez une carte du texte original vers le texte traduit. Aucune URL requise.

curl -X POST https://translator.universally.com/v1/translate/strings \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "strings": ["Welcome back", "Add to cart"],
    "targetLanguage": "fr"
  }'

Réponse :

{
  "success": true,
  "data": {
    "translations": {
      "Welcome back": "Bon retour",
      "Add to cart": "Ajouter au panier"
    },
    "metadata": {
      "sourceLanguage": "en-us",
      "targetLanguage": "fr",
      "stringsReceived": 2,
      "stringsTranslated": 2,
      "limitReached": false,
      "skippedStrings": 0
    }
  },
  "message": "Data retrieved successfully.",
  "code": "DATA_FETCHED"
}

Comment fonctionne la mise en cache

Universally met en cache chaque traduction qu'il produit, vous n'êtes donc jamais facturé deux fois pour le même contenu.

• Les traductions HTML sont mises en cache par page et par langue. Les requêtes répétées pour la même URL et la même langue cible renvoient le résultat mis en cache instantanément, et seules les chaînes nouvellement modifiées sont envoyées pour traduction.
• Les traductions de chaînes sont mises en cache par chaîne individuelle. Une fois qu'une chaîne est traduite pour une langue donnée, elle est servie depuis le cache lors de chaque requête future, quelle que soit la page ou le contexte dans lequel elle apparaît.

Vous n'avez pas besoin de gérer cela. Envoyez votre contenu à chaque requête et Universally renverra les traductions mises en cache lorsque disponibles et ne traduira que ce qui est nouveau.