API REST et agents IA (SwiftLing Pro)

Documentation / Développeurs

SwiftLing Pro permet à d’autres systèmes de lire et d’écrire des traductions : un import provenant d’une agence de traduction, un éditeur headless, un script ou une application. SwiftLing répond lui-même aux routes de WordPress dans une langue donnée et fournit la liste des langues ; voir le document docs/rest-api.md de SwiftLing. Voici ce qu’ajoute SwiftLing Pro.

Chaque requête est effectuée au nom d’un utilisateur, avec l’authentification de WordPress (un mot de passe d’application, ou le cookie et le nonce d’un utilisateur connecté), et peut faire ce que cet utilisateur est autorisé à faire dans l’éditeur de traductions : un administrateur ou un éditeur traduit ce qu’il peut modifier ; un traducteur (Réglages › Traducteurs) peut tout traduire, mais ne peut pas modifier les publications elles-mêmes. Il utilise donc les routes de swiftling-pro/v1. Ces routes fonctionnent avec les originaux, y compris à l’adresse d’une langue.

Les textes propres à une publication ou à un terme : swiftling_translations

Les publications des types traduits par SwiftLing et les termes des listes qu’il traduit possèdent un champ swiftling_translations, sur les routes de WordPress (wp/v2/posts, wp/v2/pages, wp/v2/categories…) et celles de WooCommerce (wc/v3/products, dont les produits sont des publications). Par identifiant de chaque langue :

"swiftling_translations": {
  "de": { "title": "Kontakt", "excerpt": "Schreiben Sie uns", "slug": "kontakt" }
}

Un terme possède name, description et slug. Une chaîne vide signifie qu’il n’y a pas de traduction ; si le slug est vide, celui de l’original s’affiche. Si l’original d’un texte a changé depuis sa traduction, celle-ci apparaît comme vide jusqu’à ce qu’il soit retraduit. Un visiteur ne peut lire que les langues visibles par les visiteurs ; une personne autorisée à traduire peut lire toutes les langues.

Écrit avec la publication ou le terme, comme n’importe quel autre champ, il enregistre les traductions :

POST /wp-json/wp/v2/posts/12
{ "swiftling_translations": {
    "de": { "title": "Kontakt", "excerpt": "Schreiben Sie uns", "slug": "kontakt",
            "texts": { "8f14e45fceea167a5a36dedd4bea2543": "Rufen Sie uns an" },
            "state": "machine" } } }

• title et excerpt (name et description pour un terme) sont enregistrés par leur nom ; texts contient les autres textes de la publication, par clé, tels que les répertorie GET swiftling-pro/v1/texts.
• state vaut reviewed (valeur par défaut) ou machine, pour une traduction automatique qui doit encore être vérifiée.
• Un texte vide supprime la traduction ; un slug vide rétablit celui de l’original.
• La première traduction d’un titre attribue à la publication son slug dans la langue concernée, sauf si slug est fourni.

Tout est vérifié avant le moindre enregistrement : une écriture est donc enregistrée intégralement ou pas du tout :

Sur les routes de WooCommerce, une erreur ne contient pas de data.keys : WooCommerce la renvoie dans son propre format.

Une publication qui n’a jamais été vérifiée est d’abord vérifiée sur le serveur, ce qui prend une à deux secondes.

Tout type de contenu : swiftling-pro/v1

Un sujet correspond à ce qu’ouvre l’éditeur de traductions : une publication (post:12), un modèle de thème à blocs (template:twentytwentyfive//archive), un type de page d’un thème classique (view:search), les termes d’une liste (terms:category), un menu classique (menu:3) ou un sujet provenant d’un constructeur, comme une page d’options d’Advanced Custom Fields.

GET /wp-json/swiftling-pro/v1/texts?subject=post:12&lang=de

Les textes du sujet et leurs traductions dans la langue indiquée, tels que les affiche l’éditeur. Les originaux ne sont pas stockés : la page du sujet est donc d’abord vérifiée sur le serveur.

{
  "subject": { "key": "post:12", "kind": "post", "title": "Kontakt", "url": "https://example.com/kontakt/" },
  "texts": [
    { "key": "1f0e3dad99908345f7439f8ffabdffc4", "object": "post:12", "path": "field/post_title",
      "section": "page", "kind": "heading", "type": "text", "original": "Kontakt",
      "translation": "", "state": "missing", "previous": "", "follows": false }
  ]
}

• type vaut text, html, code, url (une adresse : un lien ou une image) ou format, pour un texte issu du code qui conserve les espaces réservés de l’original.
• state vaut reviewed, machine, official (la traduction fournie par WordPress ou par le thème), outdated, avec previous, la traduction de l’original avant sa modification, ou missing.
• follows désigne le libellé d’un menu qui affiche le titre traduit de sa page tant qu’il ne possède pas sa propre traduction.
• Une clé identifie le texte et la version de son original : une traduction d’une version antérieure est refusée dès que la page a été vérifiée depuis.

POST /wp-json/swiftling-pro/v1/texts

{ "subject": "post:12", "lang": "de", "state": "reviewed",
  "texts": { "1f0e3dad99908345f7439f8ffabdffc4": "Kontakt" } }

Enregistre les traductions par clé, en effectuant les mêmes vérifications que pour les champs. La réponse indique les states des textes enregistrés, l’état de l’élément dans chaque langue (languages) et l’address d’un article dans la langue concernée.

POST /wp-json/swiftling-pro/v1/translate

{ "subject": "post:12", "lang": "de" }

Traduit les textes manquants de l’élément à l’aide du service de traduction et les enregistre comme traductions automatiques, comme le fait « Tout traduire » pour une page. Avec "again": ["machine"] (ou reviewed), il retraduit plutôt les textes dans ces états. La réponse indique le nombre de texts, le nombre de textes translated, leur nombre de characters et l’error du service si l’opération s’est arrêtée en cours de route : les traductions déjà effectuées sont conservées. Un traducteur peut l’utiliser, sauf si Réglages › Traducteurs l’interdit.

GET /wp-json/swiftling-pro/v1/to-translate?lang=de

Ce qui reste à traduire dans une langue : par défaut, les éléments non traduits, partiellement traduits, obsolètes ou traduits uniquement par une machine. La pagination suit celle des routes WordPress (page, per_page jusqu’à 100, X-WP-Total, X-WP-TotalPages).

[ { "key": "post:12", "kind": "post", "title": "Kontakt", "state": "missing",
    "url": "https://example.com/de/kontakt/", "id": 12, "type": "page" } ]

Les textes d’un élément qui n’a jamais été vérifié ne sont pas encore connus : son état est donc missing.

Une boutique : swiftling_prices et swiftling_language

Les routes WooCommerce (wc/v3) comportent deux champs supplémentaires.

Les produits et leurs variations ont un champ swiftling_prices : il contient leurs propres prix normal et promotionnel dans chacune des autres devises de la boutique (Réglages › Devises), classés par code de devise. Si un prix est vide, le produit n’a pas de prix propre dans cette devise : son prix est alors converti à partir de celui de la boutique.

"swiftling_prices": {
  "USD": { "regular": "12.50", "sale": "" },
  "GBP": { "regular": "", "sale": "" }
}

Les commandes ont un champ swiftling_language : il indique la langue dans laquelle la commande a été passée et dans laquelle les e-mails destinés au client sont rédigés, ou null si la commande a été créée dans l’interface d’administration.

"swiftling_language": { "locale": "de_DE", "slug": "de" }

Ces deux champs sont enregistrés avec le produit ou la commande, comme les champs propres à WooCommerce : les prix sous forme de chaînes contenant des nombres décimaux, au format utilisé par WooCommerce, et uniquement pour les types de prix et les devises indiqués ; la langue sous forme de slug ou de code de langue ("de"), parmi les langues du site, y compris la langue d’origine. Ils sont renseignés avant l’enregistrement par WooCommerce : une commande créée via l’API est donc enregistrée avec sa langue, et ses premiers e-mails sont envoyés dans cette langue. Une devise absente de la boutique (swiftling_currency), un prix non numérique (swiftling_price) ou une langue absente du site (swiftling_language) entraîne le rejet de la requête avec une erreur 400, avant qu’aucune de ses données soit enregistrée.

Capacités

Where WordPress has the Abilities API (6.9 and later), SwiftLing Pro registers its translation abilities in the category swiftling-translation, for AI agents (through an MCP adapter) and other tools. They are the same steps as the routes above, with the same rights, and run over the Abilities API’s own routes too: GET /wp-json/wp-abilities/v1/abilities/swiftling-pro/get-texts/run?input[subject]=post:12&input[lang]=de.