Traducir cadenas

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 una matriz de cadenas, obtén un mapa de texto de origen a traducción. Usa esto cuando tengas texto en lugar de una página: una interfaz de aplicación, una carga útil de CMS sin cabeza, texto de correo electrónico o notificaciones push.

Endpoint

POST https://translator.universally.com/v1/translate/strings
X-API-Key: your_api_key_here
Content-Type: application/json

Solicitud

{
  "strings": ["Add to cart", "Out of stock", "Free shipping over $50"],
  "targetLanguage": "de",
  "fresh": false
}

Campo	Requerido	Notas
cadenas	sí	Entre 1 y 500 entradas. Cada una debe estar no vacía.
targetLanguage	sí	Un código de idioma habilitado en el proyecto
fresco	no	true omite las traducciones almacenadas y vuelve a traducir. El valor predeterminado es false.

Nota que no hay sourceUrl aquí, a diferencia de Traducir HTML. Las cadenas no están vinculadas a una página.

Respuesta

{
  "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 se indexa por tu cadena original, por lo que puedes buscar cada una sin tener que seguir el orden de la matriz.

Manejar claves faltantes

Una cadena que no se tradujo se omite por completo de translations. Busca cada clave con un respaldo a tu propio texto:

const out = strings.map((s) => data.translations[s] ?? s);

Tres cosas causan que una clave falte:

• Nada que traducir. Un número simple, una URL, una dirección de correo electrónico, un solo carácter.
• Se agota el total de palabras. El espacio de trabajo ya estaba en su límite o por encima cuando llegó la solicitud, lo que la respuesta informa como limitReached: true con un recuento de skippedStrings.
• Un fallo transitorio al traducir ese lote.

Lee metadata para ver la forma de lo que sucedió: stringsTranslated por debajo de stringsReceived significa que algunas están ausentes.

Hay un caso especial que se comporta de manera diferente: si nada en la solicitud fue traducible en absoluto, todas las entradas se devuelven sin cambios. No te bases en eso, ya que no se aplica tan pronto como una cadena es traducible.

Deduplicación

Las cadenas repetidas en una solicitud se traducen una vez. Enviar la misma etiqueta cincuenta veces cuesta una traducción, por lo que no es necesario deducir antes de llamar.

Límites

500 cadenas por solicitud. Más de eso falla la validación. Divide conjuntos más grandes en solicitudes. El límite de 5 MB del cuerpo también se aplica aquí. Ver Errores y límites de la API.

Las reglas del glosario se aplican

Las reglas del glosario se aplican a las cadenas de la misma manera que a las páginas, por lo que un término que siempre o nunca traduces se comporta de manera consistente en ambos puntos de conexión. Ver Reglas del glosario.

Cuándo usar fresh

Déjalo en false. Las traducciones almacenadas se devuelven instantáneamente y no cuestan nada.

fresh: true traduce la cadena nuevamente y devuelve el texto nuevo sin guardarlo, por lo que es una vista previa en lugar de una forma de cambiar lo que se sirve. La siguiente solicitud normal para esa cadena aún devuelve la traducción almacenada previamente. Como no se almacena nada, una llamada fresh tampoco cuenta para su total de palabras.

Para cambiar lo que se sirve, guarde el nuevo texto en la pantalla de Traducciones. Consulte Editar traducciones manualmente.

Relacionado

• Traducir HTML
• Autentícate con la API
• Errores y límites de la API