Descripción general de la API REST

Referencia completa de la API: developer.universally.com contiene la especificación en vivo tanto para la API del Traductor como para la API de Plataforma, con cada campo, código de estado y ejemplo de respuesta. Esta página cubre lo que vale la pena saber al respecto.

Universally expone una API REST para traducir contenido web a más de 110 idiomas. La API es independiente de la plataforma: cualquier sistema que pueda realizar una solicitud HTTPS puede enviar contenido y recibir traducciones. El plugin oficial de WordPress se basa en esta misma API, pero nada aquí es específico de WordPress.

Utiliza la API cuando quieras integrar la traducción directamente en tu propia pila: un CMS personalizado, un frontend sin cabeza, un worker de borde, una aplicación móvil o web, o cualquier lugar donde el plugin no pueda llegar.

Pero como actualmente solo admitimos oficialmente la integración con WordPress, esta es más una descripción general de la API que debería permitir extender el plugin.

Dos servicios

La API está dividida en dos hosts separados. Cada uno posee un conjunto distinto de endpoints, por lo que el host te indica qué capacidad estás llamando.

Servicio de traducción

https://translator.universally.com

Aquí es donde ocurre toda la traducción. La mayoría de las integraciones solo llaman a este servicio.

Método	Endpoint	Descripción
PUBLICAR	/v1/traducir/html	Traducir un documento HTML completo
PUBLICAR	/v1/traducir/cadenas	Traducir un array de cadenas (no se requiere URL)
PUBLICAR	/v1/traducir	Detecta automáticamente HTML o cadenas del cuerpo de la solicitud
OBTENER	/salud	Comprobación de estado (sin autenticación)

Servicio de API

https://api.universally.com

Este servicio es la API de Plataforma: administra proyectos, idiomas y cadenas almacenadas desde sus propias herramientas. No la necesita para traducir.

Autenticación en resumen

Cada solicitud se autentica con una clave API enviada en el encabezado X-API-Key, y hay dos tipos. El Traductor toma la clave de 64 caracteres de su proyecto. La API de Plataforma toma una clave de espacio de trabajo que comienza con pak_ y rechaza la clave del proyecto. Dado que cualquiera de las dos puede gastar sus palabras traducidas, mantenga ambas en el lado del servidor. Consulte Autenticarse con la API.

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

Envolvente de respuesta

Cada endpoint devuelve el mismo sobre JSON, ya sea que la solicitud tenga éxito o falle:

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

• success es true para respuestas 2xx y false para errores.
• data contiene la carga útil en caso de éxito y es null en caso de error.
• code es un identificador estable y legible por máquina en el que puedes basar tu lógica. Prefiere usarlo en lugar de analizar message.

¿HTML o cadenas: qué endpoint debo usar?

El Traductor ofrece dos formas de traducir, dependiendo de la forma de tu contenido.

Utiliza /v1/translate/html cuando tengas una página renderizada. Envías un documento HTML completo junto con su URL canónica. Universally extrae cada cadena traducible, incluido el texto del cuerpo, las etiquetas meta, los datos de Open Graph, los datos estructurados, el texto alternativo de las imágenes y los atributos de los formularios, los traduce, localiza los enlaces y devuelve el HTML reescrito. Esta es la opción correcta para páginas renderizadas en el servidor e integraciones de borde.

Utiliza /v1/translate/strings cuando tengas piezas de texto discretas. Envías un array de cadenas y recibes un mapa del texto original al traducido. No se requiere URL, por lo que esta es la opción correcta para contenido que no está vinculado a una página: contenido dinámico cargado a través de AJAX, texto generado por el usuario como comentarios y reseñas, contenido de aplicaciones, notificaciones push o cualquier fragmento que tu pipeline de renderizado produzca sobre la marcha.

Si no estás seguro, envía la solicitud a /v1/translate y Universally la enviará al manejador correcto según el cuerpo que proporciones.

Ejemplos

Ambos métodos de traducción residen en el servicio Translator y se autentican con tu clave de API en la cabecera X-API-Key.

Traducir HTML

Envía una página renderizada y su URL canónica; recibe el documento traducido de vuelta.

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"
  }'

Respuesta:

{
  "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"
}

Traducir cadenas

Envía un array de cadenas; recibe un mapa del texto original al traducido. No se requiere URL.

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"
  }'

Respuesta:

{
  "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"
}

Cómo funciona el almacenamiento en caché

Universally almacena en caché cada traducción que produce, por lo que nunca se te factura dos veces por el mismo contenido.

• Las traducciones de HTML se almacenan en caché por página e idioma. Las solicitudes repetidas para la misma URL e idioma de destino devuelven el resultado en caché al instante, y solo las cadenas recién modificadas se envían a traducir.
• Las traducciones de cadenas se almacenan en caché por cadena individual. Una vez que una cadena se traduce para un idioma determinado, se sirve desde la caché en cada solicitud futura, sin importar en qué página o contexto aparezca.

No necesitas gestionar esto. Envía tu contenido en cada solicitud y Universally devuelve las traducciones en caché cuando están disponibles y traduce solo lo que es nuevo.