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 un tableau de chaînes, recevez une carte du texte source vers la traduction. Utilisez ceci lorsque vous avez du texte plutôt qu'une page : une interface d'application, une charge utile de CMS headless, le texte d'un e-mail ou des notifications push.
Point de terminaison
POST https://translator.universally.com/v1/translate/strings
X-API-Key: your_api_key_here
Content-Type: application/json
Demande
{
"strings": ["Add to cart", "Out of stock", "Free shipping over $50"],
"targetLanguage": "de",
"fresh": false
}
| Champ | Requis | Remarques |
|---|---|---|
chaînes |
oui | Entre 1 et 500 entrées. Chacune doit être non vide. |
langueCible |
oui | Un code de langue activé sur le projet |
frais |
no | true ignore les traductions stockées et traduit à nouveau. Par défaut false. |
Notez qu'il n'y a pas de sourceUrl ici, contrairement à Traduire du HTML. Les chaînes ne sont pas liées à une page.
Réponse
{
"success": true,
"data": {
"translations": {
"Add to cart": "In den Warenkorb",
"Out of stock": "Nicht auf Lager",
"Free shipping over $50": "Kostenloser Versand ab 50 $"
},
"metadata": {
"sourceLanguage": "en",
"targetLanguage": "de",
"stringsReceived": 3,
"stringsTranslated": 3,
"limitReached": false,
"skippedStrings": 0
}
},
"code": "DATA_FETCHED"
}
translations est indexé par votre chaîne d'origine, vous pouvez donc rechercher chacune sans suivre l'ordre du tableau.
Gérer les clés manquantes
Une chaîne qui n'a pas été traduite est entièrement omise de translations. Recherchez chaque clé avec un repli vers votre propre texte :
const out = strings.map((s) => data.translations[s] ?? s);
Trois raisons expliquent qu'une clé soit manquante :
- Rien à traduire. Un simple nombre, une URL, une adresse e-mail, un seul caractère.
- Le quota de mots est épuisé. L'espace de travail était déjà à sa limite ou au-dessus lorsque la requête est arrivée, ce que la réponse signale comme
limitReached: trueavec un décompteskippedStrings. - Un échec transitoire lors de la traduction de ce lot.
Lisez metadata pour connaître la structure de ce qui s'est passé : stringsTranslated inférieur à stringsReceived signifie que certains sont absents.
Il y a un cas spécial qui se comporte différemment : si rien dans la requête n'était traduisible du tout, chaque entrée est renvoyée inchangée. Ne vous basez pas là-dessus, car cela ne s'applique pas dès qu'une chaîne est traduisible.
Dédoublonnage
Les chaînes répétées dans une seule requête sont traduites une seule fois. Envoyer la même étiquette cinquante fois coûte une traduction, il n'est donc pas nécessaire de dédoublonner avant d'appeler.
Limites
500 chaînes par requête. Au-delà, la validation échoue. Divisez les ensembles plus grands en plusieurs requêtes. La limite de 5 Mo pour le corps s'applique également ici. Voir Erreurs et limites de l'API.
Les règles de glossaire s'appliquent
Les règles de glossaire s'appliquent aux chaînes de la même manière qu'aux pages, de sorte qu'un terme que vous traduisez toujours ou jamais se comporte de manière cohérente entre les deux points d'accès. Voir Règles de glossaire.
Quand utiliser fresh
Laissez-le à false. Les traductions stockées sont renvoyées instantanément et ne coûtent rien.
fresh: true traduit à nouveau la chaîne et renvoie le nouveau texte sans le stocker, il s'agit donc d'un aperçu plutôt que d'un moyen de modifier ce qui est servi. La prochaine requête ordinaire pour cette chaîne renverra toujours la traduction précédemment stockée. Comme rien n'est stocké, un appel fresh ne compte pas non plus dans votre total de mots.
Pour modifier ce qui est servi, enregistrez la nouvelle formulation sur l'écran Traductions. Voir Modifier les traductions manuellement.