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.
Envía el HTML de una página y recibe el mismo HTML con su texto traducido. Este es el endpoint que usa el plugin de WordPress y el que se debe usar para cualquier plataforma que pueda renderizar una página del lado del servidor.
Endpoint
POST https://translator.universally.com/v1/translate/html
X-API-Key: your_api_key_here
Content-Type: application/json
Solicitud
{
"html": "<html>...</html>",
"targetLanguage": "es",
"sourceUrl": "https://example.com/pricing/",
"parserMode": "auto"
}
| Campo | Requerido | Notas |
|---|---|---|
html |
sí | El documento completo o un fragmento. No debe estar vacío. |
targetLanguage |
sí | Uno de los códigos de variante configurados del proyecto, como es, es-419 o pt-br. Se rechaza un código de región como es-mx. |
sourceUrl |
sí | Debe ser una URL válida y su dominio debe coincidir con el dominio del proyecto. |
parserMode |
no | auto o classic. El valor predeterminado es auto. |
sourceUrl no es una decoración. Identifica qué página se está traduciendo para que el resultado pueda almacenarse y reutilizarse, y se verifica contra el dominio de tu proyecto. Una discrepancia devuelve TRANSLATION_SOURCE_URL_DOMAIN_MISMATCH.
Respuesta
{
"success": true,
"data": {
"translatedHtml": "<html>...</html>",
"metadata": {
"siteId": "site_123",
"siteDomain": "example.com",
"sourceLanguage": "en",
"targetLanguage": "es",
"sourceUrl": "https://example.com/pricing/",
"stringsExtracted": 142,
"stringsTranslated": 142,
"limitReached": false,
"skippedStrings": 0
}
},
"code": "DATA_FETCHED"
}
Sirve translatedHtml al visitante. Los metadatos son para tu propio registro y vale la pena grabarlos:
limitReached es true cuando el proyecto ya estaba en su total de palabras o por encima cuando llegó la solicitud. Aún obtienes HTML válido y un código 200, con texto en el idioma de origen donde se habría necesitado una nueva traducción. Consulta Límites de uso.
skippedStrings cuenta lo que quedó sin traducir. Es la única señal de omisión: se establece para el límite de palabras y nada más. Las reglas de exclusión no aparecen aquí, porque el contenido excluido se elimina antes de extraer nada. Una página excluida por completo regresa con todos los contadores en cero.
stringsExtracted frente a stringsTranslated rutinariamente difieren, y una brecha por sí sola no significa que algo estuviera mal. El texto que aparece en más de un lugar (un <title> que también es un og:title y un headline de JSON-LD), las cadenas que se omiten como intraducibles (una URL simple, una dirección de correo electrónico, un número, un solo carácter) y cualquier cosa que el límite de palabras omitió, todas lo explican.
targetLanguage repite la variante que enviaste, normalizada a minúsculas. Se compara exactamente con las variantes configuradas del proyecto en lugar de resolverse a partir de una región, razón por la cual es-mx devuelve TRANSLATION_TARGET_LANGUAGE_NOT_ALLOWED mientras que es-419 funciona. Consulta Variantes de idioma y segmentación regional.
Solicitudes comprimidas
Establece Content-Encoding: gzip y envía el cuerpo comprimido. El límite de tamaño cuenta los bytes que envías, por lo que comprimir es lo que permite que pase un documento grande.
Límites
El cuerpo de la solicitud no puede exceder los 5 MB tal como se envía, que es el tamaño comprimido cuando usas gzip. Un tamaño mayor devuelve REQUEST_TOO_LARGE con el estado 413. Consulta Errores y límites de la API.
Almacenamiento en caché de tu lado
La respuesta se almacena de nuestro lado, por lo que una solicitud repetida para la misma página e idioma es rápida y no gasta palabras nuevamente. Sigue siendo un viaje de ida y vuelta de red.
Almacena en caché el HTML traducido en tu propia capa, como lo hace el plugin de WordPress. Esa es la diferencia entre una página rápida y una página casi rápida. Consulta Rendimiento y velocidad de página.
Cuando una página está excluida
Si la ruta coincide con una regla de Páginas excluidas, el endpoint se completa correctamente con el HTML original en lugar de un error. Comprueba los metadatos si necesitas distinguir entre ambos. Consulta Excluir páginas.