Universally propose deux API, et celle dont vous avez besoin dépend de ce que vous construisez. L'une traduit du contenu, l'autre gère votre compte. Les deux sont documentées avec des exemples de requêtes en direct sur developer.universally.com.
Les deux API
| API Traducteur | API Plateforme | |
|---|---|---|
| Hôte | translator.universally.com |
api.universally.com |
| Référence | Ouvrir le schéma | Ouvrir le schéma |
| Pour | transformer du contenu dans une autre langue | gérer des projets, des langues, des glossaires et des traductions stockées |
| Clé | la clé API privée du projet | une clé API d'espace de travail |
| Utilisé par | le plugin WordPress, et votre propre intégration | scripts et outils autour du tableau de bord |
Si vous remplacez le plugin WordPress sur une autre plateforme, l'API Traducteur est celle qu'il vous faut. L'API Plateforme sert à automatiser le tableau de bord, pas à servir des pages.
D'abord, créez un projet
Un projet est ce qui contient votre domaine, votre langue source, vos langues cibles et vos clés, il précède donc tout appel API. Deux façons d'en créer un.
Dans le tableau de bord. Ouvrez Nouveau Projet. Sélectionnez Votre Technologie n'offre actuellement que WordPress : les autres options portent un badge Bientôt disponible et ne peuvent pas être sélectionnées. C'est bon pour une intégration API, car la technologie ne change que ce que le tableau de bord vous montre, pas ce que l'API Traducteur accepte. Une conséquence à prévoir : l'écran Paramètres API du projet continuera d'afficher "Plugin Universally non détecté", car pour un projet WordPress, il recherche le plugin sur votre domaine. Rien n'est faux, et la traduction fonctionne indépendamment.
Avec l'API Plateforme. POST /sites crée un projet avec une clé d'espace de travail pak_, et prend name, domain, sourceLanguage et tech. Utilisez tech: "wordpress" pour un site avec un domaine, ou tech: "app" lorsqu'il n'y a pas de domaine à fournir. tech: "website" et le mode sous-domaine sont en bêta fermée et sont rejetés pour le moment. N'envoyez pas de workspaceId : il est tiré de la clé.
curl -X POST https://api.universally.com/sites \
-H "X-API-Key: $UNIVERSALLY_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Docs site","domain":"example.com","sourceLanguage":"en-us","tech":"wordpress"}'
Ajoutez ensuite des langues cibles, soit sur l'écran Toutes les langues du projet, soit via l'API Plateforme, et copiez la clé du projet depuis Paramètres API.
L'API Traducteur
Trois points d'accès, tous POST, tous authentifiés avec la clé privée du projet dans un en-tête X-API-Key :
| Point de terminaison | Envoyez-la |
|---|---|
/v1/translate/html |
une page rendue, lorsque vous pouvez remettre du HTML entier |
/v1/translate/strings |
un tableau de chaînes, lorsque vous détenez le contenu vous-même |
/v1/translate |
l'un ou l'autre, et il décide lequel des éléments ci-dessus s'applique |
Le point de terminaison HTML est celui qui se rapproche le plus du fonctionnement du plugin : votre serveur envoie la page qu'il était sur le point de renvoyer, et renvoie ce qu'il reçoit. Rien n'a besoin de savoir à l'avance quel texte se trouve sur la page. Voir Aperçu de l'API REST pour les formes de requête et de réponse, et Erreurs et limites de l'API pour ce à quoi s'attendre lorsqu'une limite de mots est atteinte en milieu de requête.
curl -X POST https://translator.universally.com/v1/translate/html \
-H "X-API-Key: $UNIVERSALLY_KEY" \
-H "Content-Type: application/json" \
-d '{"html":"<html>...</html>","targetLanguage":"es","sourceUrl":"https://example.com/pricing/"}'
L'API de plateforme
Même en-tête, clé différente : une clé d'API d'espace de travail, qui commence par pak_. Elle atteint les mêmes points de terminaison que ceux utilisés par le tableau de bord, elle peut donc ajouter des langues, modifier les règles de glossaire, lire les traductions stockées et lister les sites sans que personne ne clique dans l'interface utilisateur.
Créez-en un sous Espaces de travail, puis Clés d'API. Voir Trouver votre clé d'API.
Ce que vous devez encore construire
Le plugin fait plus qu'appeler un point de terminaison, et rien de tout cela n'est gratuit via l'API :
- Servir les URL de langue. Quelque chose doit router
/es/pricing/vers votre réponse espagnole. Universally traduit ce que vous envoyez ; il ne se place pas devant votre site. - Mise en cache. Traduisez une fois et stockez le résultat. Renvoyer la même page ne dépense plus de mots, car une chaîne n'est facturée que la première fois qu'elle est vue, mais chaque requête coûte un aller-retour et la latence qui l'accompagne.
- Détection des modifications. Renvoyez une page lorsque son contenu change, sinon les visiteurs continueront de voir l'ancienne traduction.
- Le sélecteur de langue. Le plugin en fournit un. Via l'API, le balisage vous appartient. Voir Créer un sélecteur de langue personnalisé dans WordPress pour sa forme.