Solicite y recupere traducciones a través de la API

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

Esta API acepta contenido con estructura JSON, conservando la estructura y las claves originales. Traduce solo los valores de texto, dejando los números, los booleanos, los valores nulos y otros valores que no son de texto sin modificar.

Crear traducciones de contenido

Crea un nuevo trabajo de traducción a partir de datos con estructura JSON.

El punto final conserva la jerarquía original de claves y matrices de su contenido, traduciendo solo los valores de texto y dejando los números, los booleanos, los valores nulos y otros valores que no son de texto sin modificar.

Es especialmente útil para:

  • Gestión de contenido: localización de contenido dinámico estructurado en JSON
  • Archivos de configuración: traducción de cadenas orientadas al usuario en datos de configuración
  • Respuestas de la API: traducción de cargas útiles de respuesta estructuradas
  • Documentación: localización de contenido de ayuda o guías jerárquicas

Solicitud HTTP

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

Parámetros

ParámetroTipoObligatorioDescripción
dataobjectLos datos con estructura JSON que se van a traducir. Pueden incluir objetos anidados, matrices y valores de cadena.
namecadenaNoUn nombre legible para el trabajo de traducción. Si se omite, se genera uno automáticamente.
callback_urlcadenaNoLa URL que recibe notificaciones de webhook cuando se completa la traducción.
target_languagesarray[string]NoLa matriz de códigos ISO para 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 de cuerpo de 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 correcta

  • Código: 201 Created
  • Tipo de contenido: application/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 respuesta

CampoTipoDescripción
idnúmeroEl identificador único del trabajo de traducción de contenido.
namecadenaEl nombre del trabajo (generado automáticamente si no se proporciona).
statuscadenaEl estado actual del trabajo (queued, processing, completed).
created_atcadenaLa marca de tiempo ISO 8601 que indica cuándo se creó el trabajo.
updated_atcadenaLa marca de tiempo ISO 8601 que indica cuándo se actualizó por última vez el trabajo.

Respuestas de error

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

Procesamiento de datos JSON

Cuando se trabaja con datos con estructura JSON, PTC procesa los datos de la siguiente manera:

  • Se conserva la estructura: la jerarquía original de claves y anidamiento permanece sin cambios
  • Solo se traducen las cadenas: los números, los booleanos, las matrices y los valores nulos se mantienen tal como están
  • Traducción basada en la ruta: cada cadena traducible se identifica por su ruta JSON
  • Admite el anidamiento: funciona con objetos y matrices profundamente anidados
  • Maneja tipos de datos mixtos: los valores que no son de cadena se conservan sin modificación

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 sin cambios
  • user.settings.enabled: true → Permanece sin cambios

Flujo de trabajo de traducción

  1. Validación: se comprueban la estructura JSON y los idiomas de destino
  2. Preparación del archivo de origen: JSON se convierte a un formato de origen interno
  3. Reutilización de cadenas a través de 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 las traducciones anteriores puedan reutilizarse
  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 callback_url

Callback de webhook

Cuando se proporciona un callback_url, se envía una solicitud POST cuando se completa 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 admitidos

Tipo JSONComportamiento de la traducción
stringTraducido a los idiomas de destino
numberSe conserva tal cual
booleanSe conserva tal cual
nullSe conserva tal cual
arrayProcesado recursivamente
objectProcesado recursivamente

Ejemplo de solicitudes

Traducción JSON básica:

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -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 "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

const translationData = {
  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"
};

const response = await fetch('https://app.ptc.wpml.org/api/v1/content_translation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(translationData)
});

const result = await response.json();
console.log('Translation job created:', result);

// Store the ID for later retrieval
const translationId = result.id;

import requests

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

headers = {
    'Content-Type': 'application/json'
}

response = requests.post('https://app.ptc.wpml.org/api/v1/content_translation', 
                        headers=headers, json=translation_data)
result = response.json()

print(f"Translation job created with ID: {result['id']}")
print(f"Status: {result['status']}")
<?php
$translationData = [
    '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'
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/content_translation',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($translationData),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
echo "Translation job created with ID: " . $result['id'];
?>
const axios = require('axios');

const translationData = {
  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"
};

const response = await axios.post('https://app.ptc.wpml.org/api/v1/content_translation', translationData, {
  headers: {
    'Content-Type': 'application/json'
  }
});

console.log('Translation job created:', response.data);

// Monitor status
const checkStatus = async (id) => {
  const statusResponse = await axios.get(`https://app.ptc.wpml.org/api/v1/content_translation/${id}/status`);
  return statusResponse.data.status;
};

Obtener traducciones de contenido

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

La respuesta conserva su estructura de entrada: devuelve un objeto de origen más un objeto por cada idioma de destino (con clave por 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ámetroTipoObligatorioDescripción
identeroEl identificador único del trabajo de traducción de contenido que se va a recuperar.

Respuestas

Respuesta correcta

  • Código: 200 OK
  • Tipo de contenido: application/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 respuesta

CampoTipoDescripción
sourceobjectEl contenido de origen original en la misma estructura anidada que se envió.
{language_code}objectEl contenido traducido para cada idioma de destino, con clave 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
  • Código: 404 Not Found
{
  "error": "Content translation not found"
}
No autorizado
  • Código: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Prohibido
  • Código: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Ejemplo de solicitudes

Solicitud básica:

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

Ejemplos de código

const contentTranslationId = 123;

const response = await fetch(`https://app.ptc.wpml.org/api/v1/content_translation/${contentTranslationId}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

// Access source content
console.log('Source title:', data.source.app.title);

// Access translated content
console.log('Spanish title:', data.es.app.title);
console.log('French title:', data.fr.app.title);

// Iterate through all languages
Object.keys(data).forEach(langCode => {
  if (langCode !== 'source') {
    console.log(`${langCode} translation:`, data[langCode]);
  }
});
import requests

content_translation_id = 123
headers = {
    'Content-Type': 'application/json'
}

response = requests.get(f'https://app.ptc.wpml.org/api/v1/content_translation/{content_translation_id}', 
                       headers=headers)
data = response.json()

# Access source content
source_data = data['source']
print("Source content:", source_data)

# Access translations
for lang_code, translation in data.items():
    if lang_code != 'source':
        print(f"{lang_code.upper()} translation:", translation)
<?php
$content_translation_id = 123;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/content_translation/{$content_translation_id}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);

// Access source content
$sourceData = $data['source'];
echo "Source content: " . json_encode($sourceData, JSON_PRETTY_PRINT) . "\n";

// Access translations
foreach ($data as $langCode => $translation) {
    if ($langCode !== 'source') {
        echo strtoupper($langCode) . " translation: " . json_encode($translation, JSON_PRETTY_PRINT) . "\n";
    }
}
?>
const axios = require('axios');

const contentTranslationId = 123;

const response = await axios.get(`https://app.ptc.wpml.org/api/v1/content_translation/${contentTranslationId}`, {
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = response.data;

// Function to traverse nested objects
function extractStrings(obj, path = '') {
  const strings = [];
  for (const [key, value] of Object.entries(obj)) {
    const currentPath = path ? `${path}.${key}` : key;
    if (typeof value === 'string') {
      strings.push({ path: currentPath, value });
    } else if (typeof value === 'object') {
      strings.push(...extractStrings(value, currentPath));
    }
  }
  return strings;
}

// Extract all translatable strings
const sourceStrings = extractStrings(data.source);
console.log('Source strings:', sourceStrings);

// Compare with translations
Object.keys(data).forEach(langCode => {
  if (langCode !== 'source') {
    const translatedStrings = extractStrings(data[langCode]);
    console.log(`${langCode} strings:`, translatedStrings);
  }
});

Obtener el estado de la traducción del contenido

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 ha fallado.

Solicitud HTTP

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

Parámetros de ruta

ParámetroTipoObligatorioDescripción
identeroEl identificador único del trabajo de traducción de contenido que se va a comprobar.

Respuestas

Respuesta correcta

  • Código: 200 OK
  • Tipo de contenido: application/json
{
  "status": "completed",
  "completeness": 100
}
Esquema de respuesta
CampoTipoDescripción
statuscadenaEl estado actual de la traducción. Los posibles valores de estado incluyen: queued, in_progress, completed, failed, status_unknown.
completenessnúmeroEl porcentaje de cadenas traducidas (0–100). Calculado como (completed_translatable_strings / total_translatable_strings) × 100.
Valores de estado
EstadoDescripción
queuedLa traducción se ha puesto en cola y está esperando a ser procesada.
in_progressLa traducción se está procesando actualmente.
completedLa traducción se ha completado correctamente.
failedLa traducción ha fallado debido a un error.
status_unknownEl estado de la traducción es desconocido o aún no se puede determinar.

Respuestas de error

  • Código: 404 Not Found

Causas posibles:

  • 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
}
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status
{
  "status": "in_progress",
  "completeness": 70
}
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
  -H "Authorization: Bearer your-api-token"
{
  "status": "completed",
  "completeness": 100
}

Ir arriba