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, preservando la estructura y las claves originales. Traduce únicamente los valores de texto, dejando sin cambios los números, booleanos, nulos y otros valores que no sean de texto.
Enlaces rápidos de la API
- Crear traducciones de contenido
- Obtener traducciones de contenido
- Obtener el estado de la traducción del contenido
Crear traducciones de contenido
Crea un nuevo trabajo de traducción a partir de datos estructurados en JSON.
El endpoint preserva la jerarquía original de claves y arrays de su contenido, traduciendo solo los valores de texto mientras mantiene intactos los números, booleanos, nulos y otros valores que no sean de texto.
Es especialmente útil para:
- Gestión de contenidos – 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 API – Traducción de payloads de respuesta estructurados
- Documentación – Localización de guías o contenido de ayuda jerárquico
Para una implementación completa en Rails de este flujo de trabajo, consulte cómo traducir contenido dinámico en Rails usando la API de PTC.
Solicitud HTTP
POST https://app.ptc.wpml.org/api/v1/content_translationParámetros
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
data |
object | Sí | Los datos estructurados en JSON que se van a traducir. Puede incluir objetos anidados, arrays y valores de cadena. |
name |
string | No | Un nombre legible para el trabajo de traducción. Si se omite, se genera uno automáticamente. |
callback_url |
string | No | La URL que recibe notificaciones por webhook cuando la traducción se ha completado. |
target_languages |
array[string] | No | El array de códigos ISO para los idiomas de destino. Si se omite, las traducciones se crean 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 correcta
{
"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
| Campo | Tipo | Descripción |
|---|---|---|
id |
number | El identificador único del trabajo de traducción de 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
{
"errors": {
"data": ["Data must be a valid JSON object"]
}
}Idiomas de destino no válidos
{
"errors": {
"target_languages": ["Language codes [zh, xx] are not configured for this project"]
}
}No autorizado
{
"error": "Unauthorized access. Please provide a valid API token."
}Prohibido
{
"error": "Access denied. Insufficient permissions."
}Procesamiento de datos JSON
Al trabajar con datos estructurados en JSON, PTC procesa la información de la siguiente manera:
- Se preserva la estructura – La jerarquía original de claves y anidamiento permanece inalterada
- Solo se traducen las cadenas – Los números, booleanos, arrays y valores nulos se mantienen tal cual
- Traducción basada en rutas – Cada cadena traducible se identifica por su ruta JSON
- Soporta anidamiento – Funciona con objetos y arrays profundamente anidados
- Gestiona tipos de datos mixtos – Los valores que no son cadenas se preservan 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 traduceuser.settings.theme: “Choose Theme” → Se traduceuser.settings.count:5 → Permanece sin cambiosuser.settings.enabled:true → Permanece sin cambios
Flujo de trabajo de traducción
- Validación: se comprueban la estructura JSON y los idiomas de destino
- Preparación del archivo de origen: el JSON se convierte a un formato de origen interno
- Reutilización de cadenas mediante la memoria de traducción: se extraen todas las cadenas traducibles y se almacenan en la memoria de traducción de su proyecto para que las traducciones anteriores puedan reutilizarse
- Cola de trabajos: se pone en cola un trabajo para cada idioma de destino
- Procesamiento: la traducción automática se ejecuta sobre las cadenas extraídas
- 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 finalizar 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 |
Traducido a los idiomas de destino |
number |
Preservado tal cual |
boolean |
Preservado tal cual |
null |
Preservado tal cual |
array |
Procesado recursivamente |
object |
Procesado recursivamente |
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 (status stays
# "in_progress" until done — it is not set on the create response):
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/CONTENT_TRANSLATION_ID/status" \
-H "Authorization: Bearer YOUR_API_TOKEN"require 'net/http'
require 'uri'
require 'json'
uri = URI('https://app.ptc.wpml.org/api/v1/content_translation')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
data: { app: { title: 'My Application',
navigation: { home: 'Home', about: 'About Us' } } },
name: 'App Translations',
target_languages: %w[es fr de],
callback_url: 'https://your-app.com/webhooks/complete'
}.to_json
response = http.request(request)
id = JSON.parse(response.body)['id']
puts "Translation job created with ID: #{id}"
# Poll the status endpoint for progress (status is set there, not on create)
status_uri = URI("https://app.ptc.wpml.org/api/v1/content_translation/#{id}/status")
status_request = Net::HTTP::Get.new(status_uri)
status_request['Authorization'] = 'Bearer YOUR_API_TOKEN'
status = JSON.parse(http.request(status_request).body)
puts "Status: #{status['status']} (#{status['completeness']}% complete)"import requests
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
}
payload = {
"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"
}
response = requests.post('https://app.ptc.wpml.org/api/v1/content_translation', headers=headers, json=payload)
translation_id = response.json()['id']
print(f"Translation job created with ID: {translation_id}")
# Poll the status endpoint for progress (status is set there, not on create)
status_response = requests.get(f'https://app.ptc.wpml.org/api/v1/content_translation/{translation_id}/status', headers=headers)
status = status_response.json()
print(f"Status: {status['status']} ({status['completeness']}% complete)")<?php
$payload = [
'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($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Content-Type: application/json'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$id = json_decode($response, true)['id'];
echo "Translation job created with ID: " . $id . "\n";
// Poll the status endpoint for progress (status is set there, not on create)
$statusCurl = curl_init();
curl_setopt_array($statusCurl, [
CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/content_translation/{$id}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_TOKEN'],
]);
$status = json_decode(curl_exec($statusCurl), true);
curl_close($statusCurl);
echo "Status: " . $status['status'] . " (" . $status['completeness'] . "% complete)";
?>import okhttp3.*;
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json");
String payload = "{"
+ "\"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\"}";
Request request = new Request.Builder()
.url("https://app.ptc.wpml.org/api/v1/content_translation")
.addHeader("Authorization", "Bearer YOUR_API_TOKEN")
.post(RequestBody.create(payload, JSON))
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{
"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"
}`)
req, _ := http.NewRequest("POST", "https://app.ptc.wpml.org/api/v1/content_translation", bytes.NewBuffer(payload))
req.Header.Add("Authorization", "Bearer YOUR_API_TOKEN")
req.Header.Add("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
var payload = @"{
""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""
}";
var body = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://app.ptc.wpml.org/api/v1/content_translation", body);
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);const axios = require('axios');
const payload = {
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', payload, {
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const translationId = response.data.id;
console.log('Translation job created with ID:', translationId);
// Poll the status endpoint for progress (status is set there, not on create)
const status = await axios.get(`https://app.ptc.wpml.org/api/v1/content_translation/${translationId}/status`, {
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
console.log(`Status: ${status.data.status} (${status.data.completeness}% complete)`);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 preserva la estructura de entrada: devuelve un objeto de origen (source) 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 | Requerido | Descripción |
|---|---|---|---|
id |
integer | Sí | El identificador único del trabajo de traducción de contenido que se desea recuperar. |
Respuestas
Respuesta correcta
{
"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
| Campo | Tipo | Descripción |
|---|---|---|
source |
object | El contenido original de origen con la misma estructura anidada 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 más información, consulte la API de idiomas de destino disponibles. |
Respuestas de error
Traducción de contenido no encontrada
{
"error": "Content translation not found"
}No autorizado
{
"error": "Unauthorized access. Please provide a valid API token."
}Prohibido
{
"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"require 'net/http'
require 'uri'
uri = URI('https://app.ptc.wpml.org/api/v1/content_translation/123')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
response = http.request(request)
require 'json'
data = JSON.parse(response.body)
puts "Source: #{data['source']}"
data.each { |lang, translation| puts "#{lang}: #{translation}" unless lang == 'source' }import requests
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
response = requests.get('https://app.ptc.wpml.org/api/v1/content_translation/123', headers=headers)
data = response.json()
print('Source:', data['source'])
for lang_code, translation in data.items():
if lang_code != 'source':
print(f"{lang_code}:", translation)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/content_translation/123',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
foreach ($data as $langCode => $translation) {
echo strtoupper($langCode) . ": " . json_encode($translation) . "\n";
}
?>import okhttp3.*;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://app.ptc.wpml.org/api/v1/content_translation/123")
.addHeader("Authorization", "Bearer YOUR_API_TOKEN")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://app.ptc.wpml.org/api/v1/content_translation/123", nil)
req.Header.Add("Authorization", "Bearer YOUR_API_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
var response = await client.GetAsync("https://app.ptc.wpml.org/api/v1/content_translation/123");
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);const axios = require('axios');
const response = await axios.get('https://app.ptc.wpml.org/api/v1/content_translation/123', {
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const data = response.data;
console.log('Source:', data.source);
Object.keys(data).forEach(lang => {
if (lang !== 'source') console.log(`${lang}:`, data[lang]);
});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 indica 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}/statusParámetros de ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
id |
integer | Sí | El identificador único del trabajo de traducción de contenido que se desea consultar. |
Respuestas
Respuesta correcta
{
"status": "completed",
"completeness": 100
}Esquema de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
status |
string | El estado actual de la traducción. Los posibles valores de estado incluyen: queued, in_progress, completed, failed, status_unknown. |
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 |
|---|---|
queued |
La traducción se ha puesto en cola y está esperando a 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. |
status_unknown |
El estado de la traducción es desconocido o aún no se puede determinar. |
Respuestas de error
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
}Respuesta mientras el trabajo aún se está ejecutando:
{
"status": "in_progress",
"completeness": 70
}{
"status": "completed",
"completeness": 100
}