PTC

Solicitar y recuperar traducciones a través de la API

Utilice esta API para enviar contenido para su traducción, realizar un seguimiento de su progreso y recuperar las traducciones en todos los idiomas de destino.

Esta API acepta contenido estructurado en JSON, conservando la estructura y las claves originales. Solo traduce los valores de texto, dejando intactos los números, los booleanos, los nulos y otros valores que no son de texto.

Create Content Translations

Crea un nuevo trabajo de traducción a partir de datos estructurados en JSON.

El endpoint conserva la jerarquía original de claves y arrays de su contenido, traduciendo solo los valores de texto y dejando intactos los números, los booleanos, los nulos y otros valores que no son de texto.

Resulta especialmente útil para:

  • Gestión de contenido: localizar contenido dinámico estructurado en JSON
  • Archivos de configuración: traducir cadenas orientadas al usuario en los datos de configuración
  • Respuestas de la API: traducir payloads de respuesta estructurados
  • Documentación: localizar guías o contenido de ayuda jerárquico

Para ver una implementación completa de este flujo de trabajo en Rails, consulte cómo traducir contenido dinámico en Rails utilizando la API de PTC.

Solicitud HTTP

POST https://app.ptc.wpml.org/api/v1/content_translation

Parámetros

Parámetro Tipo Obligatorio Descripción
data object Sí Los datos estructurados en JSON que se van a traducir. Pueden incluir objetos anidados, arrays y valores de cadena.
name string No Un nombre legible por humanos para el trabajo de traducción. Si se omite, se genera uno automáticamente.
callback_url string No La URL que recibe notificaciones de webhook cuando se completa la traducción.
target_languages array[string] No El array de códigos ISO de los idiomas de destino. Si se omite, se crean traducciones para todos los idiomas configurados en el proyecto. Consulte la API de idiomas de destino disponibles para obtener más información.

Ejemplo del cuerpo de la solicitud

{
  "data": {
    "app": {
      "title": "My Application",
      "navigation": {
        "home": "Home",
        "about": "About Us",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Save",
        "cancel": "Cancel",
        "submit": "Submit"
      },
      "messages": {
        "welcome": "Welcome to our platform",
        "error": "An error occurred"
      }
    },
    "version": "1.0.0",
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  },
  "name": "App UI Translations",
  "callback_url": "https://your-app.com/webhooks/translation-complete",
  "target_languages": ["es", "fr", "de"]
}

Respuestas

Respuesta de éxito

201 Createdapplication/json
{
  "id": 123,
  "name": "App UI Translations",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

Esquema de la respuesta

Campo Tipo Descripción
id number El identificador único del trabajo de traducción del contenido.
name string El nombre del trabajo (generado automáticamente si no se proporciona).
status string El estado actual del trabajo (queued, processing, completed).
created_at string La marca de tiempo ISO 8601 que indica cuándo se creó el trabajo.
updated_at string La marca de tiempo ISO 8601 que indica cuándo se actualizó el trabajo por última vez.

Respuestas de error

Datos JSON no válidos
422 Unprocessable Entity
{
  "errors": {
    "data": ["Data must be a valid JSON object"]
  }
}
Idiomas de destino no válidos
422 Unprocessable Entity
{
  "errors": {
    "target_languages": ["Language codes [zh, xx] are not configured for this project"]
  }
}
No autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Prohibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Procesamiento de datos JSON

Al trabajar con datos estructurados en JSON, PTC procesa los datos de la siguiente manera:

  • Se conserva la estructura: la jerarquía original de claves y anidamiento permanece intacta
  • Solo se traducen las cadenas: los números, los booleanos, los arrays y los valores nulos se mantienen tal cual
  • Traducción basada en rutas: cada cadena traducible se identifica mediante su ruta JSON
  • Admite anidamiento: funciona con objetos y arrays profundamente anidados
  • Procesa tipos de datos mixtos: los valores que no son cadenas se conservan sin modificaciones

Ejemplo de transformación de datos

Entrada:

{
  "user": {
    "name": "Welcome User",
    "settings": {
      "theme": "Choose Theme",
      "count": 5,
      "enabled": true
    }
  }
}

Resultado del procesamiento:

  • user.name: “Welcome User” → Se traduce
  • user.settings.theme: “Choose Theme” → Se traduce
  • user.settings.count: 5 → Permanece intacto
  • user.settings.enabled: true → Permanece intacto

Flujo de trabajo de traducción

  1. Validación: se comprueban la estructura del JSON y los idiomas de destino
  2. Preparación del archivo de origen: el JSON se convierte a un formato de origen interno
  3. Reutilización de cadenas mediante la memoria de traducción: todas las cadenas traducibles se extraen y se almacenan en la memoria de traducción de su proyecto para que se puedan reutilizar las traducciones anteriores
  4. Puesta en cola de trabajos: se pone en cola un trabajo para cada idioma de destino
  5. Procesamiento: la traducción automática se ejecuta en las cadenas extraídas
  6. Callback (opcional): se envía un webhook cuando se completan todas las traducciones, si se proporciona una callback_url

Callback de webhook

Cuando se proporciona una callback_url, se envía una solicitud POST al completarse el trabajo.

Cuerpo de la solicitud de callback:

{
  "id": 1,
  "status": "completed",
  "translations_url": "https://app.ptc.wpml.org/api/v1/content_translation/1"
}

Tipos de datos compatibles

Tipo JSON Comportamiento de traducción
string Se traduce a los idiomas de destino
number Se conserva tal cual
boolean Se conserva tal cual
null Se conserva tal cual
array Se procesa de forma recursiva
object Se procesa de forma recursiva

Ejemplos de solicitudes

Traducción básica de JSON:

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "welcome": "Welcome",
      "buttons": {
        "save": "Save",
        "cancel": "Cancel"
      }
    },
    "name": "UI Labels"
  }'

Con idiomas de destino específicos:

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "title": "Product Catalog",
      "categories": {
        "electronics": "Electronics",
        "clothing": "Clothing"
      }
    },
    "target_languages": ["es", "fr"],
    "callback_url": "https://myapp.com/webhook"
  }'

Ejemplos de código

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"app":{"title":"My Application","navigation":{"home":"Home","about":"About Us"}}},"name":"App Translations","target_languages":["es","fr","de"],"callback_url":"https://your-app.com/webhooks/complete"}'

# The response includes the job "id". Poll its status (the create response
# carries a "status" field as well, but it is usually null until the run
# starts, and stays "in_progress" until done):
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/CONTENT_TRANSLATION_ID/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get Content Translations

Recupera el contenido original y todas las versiones traducidas de un trabajo de traducción de contenido específico.

La respuesta conserva la estructura de entrada: devuelve un objeto de origen más un objeto por cada idioma de destino (identificado por el código de idioma, como es, fr, de).

Solicitud HTTP

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}

Parámetros de ruta

Parámetro Tipo Obligatorio Descripción
id integer Sí El identificador único del trabajo de traducción de contenido que se va a recuperar.

Respuestas

Respuesta de éxito

200 OKapplication/json
{
  "source": {
    "app": {
      "title": "My Application",
      "navigation": {
        "home": "Home",
        "about": "About",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Save",
        "cancel": "Cancel"
      }
    }
  },
  "es": {
    "app": {
      "title": "Mi Aplicación",
      "navigation": {
        "home": "Inicio",
        "about": "Acerca de",
        "contact": "Contacto"
      },
      "buttons": {
        "save": "Guardar",
        "cancel": "Cancelar"
      }
    }
  },
  "fr": {
    "app": {
      "title": "Mon Application",
      "navigation": {
        "home": "Accueil",
        "about": "À propos",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Enregistrer",
        "cancel": "Annuler"
      }
    }
  }
}

Esquema de la respuesta

Campo Tipo Descripción
source object El contenido de origen original en la misma estructura anidada en la que se envió.
{language_code} object El contenido traducido para cada idioma de destino, identificado por su código ISO (por ejemplo, es, fr, de), con la misma estructura que el origen. Para obtener más información, consulte la API de idiomas de destino disponibles.

Respuestas de error

Traducción de contenido no encontrada
404 Not Found
{
  "error": "Content translation not found"
}
No autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Prohibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Ejemplos de solicitudes

Solicitud básica:

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Ejemplos de código

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get the Content Translation Status

Recupera el estado actual de un trabajo de traducción de contenido específico.

La respuesta refleja el progreso general e incluye si la traducción está en cola, en curso, completada o si ha fallado.

Solicitud HTTP

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status

Parámetros de ruta

Parámetro Tipo Obligatorio Descripción
id integer Sí El identificador único del trabajo de traducción de contenido que se va a comprobar.

Respuestas

Respuesta de éxito

200 OKapplication/json
{
  "status": "completed",
  "completeness": 100
}
Esquema de la respuesta
Campo Tipo Descripción
status string El estado de la traducción actual. Los posibles valores de estado son: draft, queued, in_progress, completed, failed, out_of_credit y null.
completeness number El porcentaje de cadenas traducidas (0–100). Se calcula como (completed_translatable_strings / total_translatable_strings) × 100.
Valores de estado
Estado Descripción
draft El archivo de origen está registrado pero aún no tiene ningún archivo adjunto, por lo que no hay nada que traducir.
queued La traducción se ha puesto en cola y está a la espera de ser procesada.
in_progress La traducción se está procesando actualmente.
completed La traducción se ha completado correctamente.
failed La traducción ha fallado debido a un error.
out_of_credit La traducción se ha detenido porque el proyecto se ha quedado sin crédito. Este es un estado final: la ejecución no se reanuda por sí sola una vez que se añade crédito, por lo que debe consultar su estado del mismo modo que lo haría para failed.
null Ninguna traducción ha alcanzado aún ninguno de los estados anteriores. Es normal que esto ocurra justo después de crear una traducción de contenido, y debe tratarlo como «no iniciado» en lugar de como un error.

Respuestas de error

404 Not Found

Posibles causas:

  • No existe ninguna traducción de contenido con el ID especificado
  • El trabajo de traducción no pertenece al proyecto autenticado

Ejemplo

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Respuesta:

{
  "status": "completed",
  "completeness": 100
}

Respuesta mientras el trabajo aún se está ejecutando:

{
  "status": "in_progress",
  "completeness": 70
}
{
  "status": "completed",
  "completeness": 100
}