Solicitar y recuperar traducciones mediante la API
Use 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 y conserva la estructura y las claves originales. Traduce solo los valores de texto, dejando intactos los números, los booleanos, los valores nulos y otros valores que no son de texto.
Enlaces rápidos de la API
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 mientras deja intactos los números, los booleanos, los valores nulos y otros valores que no son de texto.
Es especialmente útil para:
- Gestión de contenido: localizar contenido dinámico estructurado en JSON
- Archivos de configuración: traducir cadenas de cara al usuario en datos de configuración
- Respuestas de la API: traducir payloads de respuesta estructurados
- Documentación: localizar contenido de ayuda o guías jerárquicos
Para ver una implementación completa de este flujo de trabajo en Rails, 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 |
objeto | Sí | Los datos estructurados en JSON que se van a traducir. Pueden incluir objetos anidados, arrays y valores de cadena. |
name |
cadena | No | Un nombre legible para el trabajo de traducción. Si se omite, se genera uno automáticamente. |
callback_url |
cadena | No | La URL que recibe notificaciones de webhook cuando se completa la traducción. |
target_languages |
array[cadena] | No | El array 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 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
{
"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 |
número | El identificador único del trabajo de traducción de contenido. |
name |
cadena | El nombre del trabajo (generado automáticamente si no se proporciona). |
status |
cadena | El estado actual del trabajo (queued, processing, completed). |
created_at |
cadena | La marca de tiempo ISO 8601 que indica cuándo se creó el trabajo. |
updated_at |
cadena | 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 los datos de la siguiente manera:
- Se conserva la estructura: la jerarquía original de las claves y el anidamiento se mantiene sin cambios
- 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 mediante su ruta JSON
- Admite anidamiento: funciona con objetos y arrays profundamente anidados
- Admite 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 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: 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
- Puesta en cola del trabajo: se pone en cola un trabajo para cada idioma de destino
- Procesamiento: la traducción automática se ejecuta en las cadenas extraídas
- Callback (opcional): se envía un webhook cuando se completan todas las traducciones, si se proporciona
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 del callback:
{
"id": 1,
"status": "completed",
"translations_url": "https://app.ptc.wpml.org/api/v1/content_translation/1"
}Tipos de datos admitidos
| Tipo JSON | Comportamiento de la 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 recursivamente |
object |
Se procesa 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)`);Get Content Translations
Recupera el contenido original y todas las versiones traducidas para 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 idioma de destino (identificado mediante 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 |
entero | Sí | El identificador único del trabajo de traducción de contenido que se va a recuperar. |
Respuestas
Respuesta de éxito
{
"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 |
objeto | El contenido de origen original en la misma estructura anidada que se envió. |
{language_code} |
objeto | 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
{
"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]);
});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}/statusParámetros de ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
id |
entero | Sí | El identificador único del trabajo de traducción de contenido que se va a comprobar. |
Respuestas
Respuesta de éxito
{
"status": "completed",
"completeness": 100
}Esquema de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
status |
cadena | El estado actual de la traducción. Los posibles valores de estado incluyen: queued, in_progress, completed, failed, status_unknown. |
completeness |
número | El porcentaje de cadenas traducidas (0–100). Calculado 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á a la espera de ser procesada. |
in_progress |
La traducción se está procesando actualmente. |
completed |
La traducción se ha completado con éxito. |
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
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 todavía se está ejecutando:
{
"status": "in_progress",
"completeness": 70
}{
"status": "completed",
"completeness": 100
}