API REST y agentes de IA (SwiftLing Pro)

Documentación / Desarrolladores

SwiftLing Pro permite a otros sistemas leer y escribir traducciones: una importación de una agencia de traducción, un editor desacoplado, un script o una aplicación. SwiftLing ya responde a las rutas de WordPress en un idioma y enumera los idiomas; consulta docs/rest-api.md de SwiftLing. Esto es lo que añade SwiftLing Pro.

Cada solicitud se realiza en nombre de un usuario, mediante la autenticación de WordPress (una contraseña de aplicación o la cookie y el nonce de un usuario que haya iniciado sesión), y puede hacer lo que ese usuario tenga permitido en el editor de traducciones: un administrador o editor traduce lo que puede editar; un traductor (Ajustes › Traductores) puede traducirlo todo, pero no modificar las entradas en sí, por lo que utiliza las rutas de swiftling-pro/v1. Estas rutas funcionan con los originales, también desde la dirección de un idioma.

Los textos propios de una entrada o un término: swiftling_translations

Las entradas de los tipos que traduce SwiftLing y los términos de las listas que traduce tienen un campo swiftling_translations, tanto en las rutas de WordPress (wp/v2/posts, wp/v2/pages, wp/v2/categories…) como en las de WooCommerce (wc/v3/products, cuyos productos son entradas). Se organiza por el slug de cada idioma:

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

Un término tiene name, description y slug. Una cadena vacía significa que no hay traducción; si el slug está vacío, se muestra el del original. Un texto cuyo original haya cambiado desde que se tradujo aparece vacío hasta que se vuelva a traducir. Los visitantes solo pueden leer los idiomas visibles para ellos; quienes pueden traducir tienen acceso a todos los idiomas.

Si se incluye al escribir la entrada o el término, se guardan las traducciones como cualquier otro campo:

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 y excerpt (name y description en un término) se guardan por nombre; texts contiene los demás textos de la entrada, identificados por clave, tal como los enumera GET swiftling-pro/v1/texts.
• state es reviewed (el valor predeterminado) o machine, para una traducción automática pendiente de revisión.
• Un texto vacío elimina la traducción; un slug vacío restaura el del original.
• La primera traducción de un título asigna a la entrada su slug en ese idioma, salvo que se proporcione slug.

Se comprueba todo antes de guardar nada, por lo que una operación de escritura se guarda íntegramente o no se guarda:

A través de las rutas de WooCommerce, un error no contiene data.keys: WooCommerce lo devuelve con su propio formato.

Una entrada que nunca se haya analizado se analiza primero en el servidor, lo que tarda uno o dos segundos.

Cualquier elemento: swiftling-pro/v1

Un elemento es aquello que abre el editor de traducciones: una entrada (post:12), una plantilla de un tema de bloques (template:twentytwentyfive//archive), un tipo de página de un tema clásico (view:search), los términos de una lista (terms:category), un menú clásico (menu:3) o un elemento de un maquetador, como una página de opciones de Advanced Custom Fields.

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

Los textos del elemento con sus traducciones al idioma, tal como aparecen en el editor. Los originales no se almacenan, por lo que primero se analiza la página del elemento en el servidor.

{
  "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 es text, html, code, url (una dirección: un enlace o una imagen) o format, un texto procedente del código que conserva los marcadores de posición del original.
• state es reviewed, machine, official (la traducción propia de WordPress o del tema), outdated, con previous, la traducción del original antes de que cambiara, o missing.
• follows indica que la etiqueta de un menú muestra el título traducido de su página mientras no tenga una traducción propia.
• Una clave identifica el texto y la versión de su original: se rechaza una traducción de una versión anterior si la página se ha analizado desde entonces.

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

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

Guarda las traducciones por clave y las comprueba igual que los campos. Devuelve los states de lo guardado, el estado del elemento en cada idioma (languages) y la address de una entrada en ese idioma.

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

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

Rellena los textos vacíos del elemento mediante el servicio de traducción y los guarda como traducciones automáticas, igual que hace Traducir todo con una página. Con "again": ["machine"] (o reviewed), vuelve a traducir los textos que estén en esos estados. Devuelve cuántos texts había, cuántos se han translated, sus characters y el error del servicio si se ha detenido a mitad del proceso: se conserva lo traducido hasta ese momento. Un traductor puede usarlo, salvo que se haya desactivado en Ajustes › Traductores.

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

Lo que aún falta por traducir a un idioma: por defecto, lo que no está traducido, está traducido parcialmente, está desactualizado o solo tiene traducción automática. Se pagina como las rutas de WordPress (page, per_page hasta 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" } ]

Un elemento que nunca se ha comprobado aún no tiene textos conocidos, por lo que figura como missing.

Una tienda: swiftling_prices y swiftling_language

Las rutas de WooCommerce (wc/v3) incluyen dos campos más.

Los productos y sus variaciones tienen swiftling_prices: el precio normal y el precio rebajado propios del producto en cada una de las demás monedas de la tienda (Ajustes › Monedas), identificadas por su código. Si un precio está vacío, el producto no tiene un precio propio en esa moneda, por lo que se convierte a partir del precio en la moneda de la tienda.

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

Los pedidos tienen swiftling_language: el idioma en el que se realizó el pedido y en el que se escriben los correos electrónicos enviados al cliente, o null si se creó desde el panel de administración.

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

Ambos se guardan con el producto o el pedido, como los campos propios de WooCommerce: los precios, como números decimales en cadenas de texto, tal como los guarda WooCommerce, y solo para los tipos y las monedas indicados; el idioma, mediante su slug o configuración regional ("de"), que debe ser uno de los idiomas del sitio, incluido el original. Se escriben antes de que WooCommerce guarde los datos, por lo que un pedido creado mediante la API se guarda con su idioma y los primeros correos electrónicos se envían en ese idioma. Una moneda que la tienda no tenga (swiftling_currency), un precio que no sea un número (swiftling_price) o un idioma que el sitio no tenga (swiftling_language) detienen la solicitud con un error 400 antes de que se guarde ninguno de sus datos.

Funcionalidades

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.