Solicite e recupere traduções via API
Use esta API para enviar conteúdo para tradução, acompanhar seu progresso e recuperar as traduções em todos os idiomas de destino.
Esta API aceita conteúdo estruturado em JSON, preservando a estrutura original e as chaves. Ela traduz apenas valores de texto, deixando números, booleanos, nulos e outros valores que não são texto inalterados.
Links rápidos da API
Create Content Translations
Cria uma nova tarefa de tradução a partir de dados estruturados em JSON.
O endpoint preserva a hierarquia original de chaves e arrays do seu conteúdo, traduzindo apenas valores de texto enquanto deixa números, booleanos, nulos e outros valores que não são texto inalterados.
Ele é especialmente útil para:
- Gerenciamento de conteúdo – Localização de conteúdo dinâmico estruturado em JSON
- Arquivos de configuração – Tradução de strings voltadas para o usuário em dados de configuração
- Respostas de API – Tradução de payloads de resposta estruturados
- Documentação – Localização de guias ou conteúdo de ajuda hierárquico
Para uma implementação completa desse fluxo de trabalho em Rails, consulte a tradução de conteúdo dinâmico em Rails usando a API da PTC.
Requisição HTTP
POST https://app.ptc.wpml.org/api/v1/content_translationParâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
data |
object | Sim | Os dados estruturados em JSON para traduzir. Podem incluir objetos aninhados, arrays e valores de string. |
name |
string | Não | Um nome legível por humanos para a tarefa de tradução. Se omitido, um será gerado automaticamente. |
callback_url |
string | Não | A URL que recebe notificações de webhook quando a tradução é concluída. |
target_languages |
array[string] | Não | O array de códigos ISO para os idiomas de destino. Se omitido, as traduções são criadas para todos os idiomas configurados no projeto. Consulte a API de Idiomas de Destino Disponíveis para obter mais informações. |
Exemplo de corpo da requisição
{
"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"]
}Respostas
Resposta de sucesso
{
"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 da resposta
| Campo | Tipo | Descrição |
|---|---|---|
id |
number | O identificador exclusivo da tarefa de tradução de conteúdo. |
name |
string | O nome da tarefa (gerado automaticamente se não for fornecido). |
status |
string | O status atual da tarefa (queued, processing, completed). |
created_at |
string | O timestamp ISO 8601 indicando quando a tarefa foi criada. |
updated_at |
string | O timestamp ISO 8601 indicando quando a tarefa foi atualizada pela última vez. |
Respostas de erro
Dados JSON inválidos
{
"errors": {
"data": ["Data must be a valid JSON object"]
}
}Idiomas de destino inválidos
{
"errors": {
"target_languages": ["Language codes [zh, xx] are not configured for this project"]
}
}Não autorizado
{
"error": "Unauthorized access. Please provide a valid API token."
}Proibido
{
"error": "Access denied. Insufficient permissions."
}Processamento de dados JSON
Ao trabalhar com dados estruturados em JSON, a PTC processa os dados da seguinte forma:
- A estrutura é preservada – A hierarquia original de chaves e aninhamento permanece inalterada
- Apenas strings são traduzidas – Números, booleanos, arrays e valores nulos são mantidos como estão
- Tradução baseada em caminho – Cada string traduzível é identificada pelo seu caminho JSON
- Suporta aninhamento – Funciona com objetos e arrays profundamente aninhados
- Lida com tipos de dados mistos – Valores que não são strings são preservados sem modificação
Exemplo de transformação de dados
Entrada:
{
"user": {
"name": "Welcome User",
"settings": {
"theme": "Choose Theme",
"count": 5,
"enabled": true
}
}
}Resultado do processamento:
user.name: “Welcome User” → É traduzidouser.settings.theme: “Choose Theme” → É traduzidouser.settings.count:5 → Permanece inalteradouser.settings.enabled:true → Permanece inalterado
Fluxo de trabalho de tradução
- Validação: A estrutura JSON e os idiomas de destino são verificados
- Preparação do arquivo de origem: O JSON é convertido para um formato de origem interno
- Reutilização de strings por meio da memória de tradução: Todas as strings traduzíveis são extraídas e armazenadas na memória de tradução do seu projeto para que traduções anteriores possam ser reutilizadas
- Enfileiramento de tarefas: Uma tarefa é colocada na fila para cada idioma de destino
- Processamento: A tradução automática é executada nas strings extraídas
- Callback (opcional): Um webhook é enviado quando todas as traduções são concluídas, se a
callback_urlfor fornecida
Callback de webhook
Quando uma callback_url é fornecida, uma requisição POST é enviada quando a tarefa é concluída.
Corpo da requisição de callback:
{
"id": 1,
"status": "completed",
"translations_url": "https://app.ptc.wpml.org/api/v1/content_translation/1"
}Tipos de dados suportados
| Tipo JSON | Comportamento de tradução |
|---|---|
string |
Traduzido para os idiomas de destino |
number |
Preservado como está |
boolean |
Preservado como está |
null |
Preservado como está |
array |
Processado recursivamente |
object |
Processado recursivamente |
Exemplos de requisição
Tradução 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"
}'Com 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"
}'Exemplos 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 o conteúdo original e todas as versões traduzidas para uma tarefa de tradução de conteúdo específica.
A resposta preserva sua estrutura de entrada: ela retorna um objeto de origem mais um objeto por idioma de destino (com a chave sendo o código do idioma, como es, fr, de).
Requisição HTTP
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}Parâmetros de caminho
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
integer | Sim | O identificador exclusivo da tarefa de tradução de conteúdo a ser recuperada. |
Respostas
Resposta de sucesso
{
"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 da resposta
| Campo | Tipo | Descrição |
|---|---|---|
source |
object | O conteúdo de origem original na mesma estrutura aninhada em que foi enviado. |
{language_code} |
object | O conteúdo traduzido para cada idioma de destino, usando seu código ISO como chave (por exemplo, es, fr, de), com a mesma estrutura da origem. Para obter mais informações, consulte a API de Idiomas de Destino Disponíveis. |
Respostas de erro
Tradução de conteúdo não encontrada
{
"error": "Content translation not found"
}Não autorizado
{
"error": "Unauthorized access. Please provide a valid API token."
}Proibido
{
"error": "Access denied. Insufficient permissions."
}Exemplos de requisição
Requisição 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"Exemplos 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 o status atual de uma tarefa de tradução de conteúdo específica.
A resposta reflete o progresso geral e inclui se a tradução está na fila, em andamento, concluída ou se falhou.
Requisição HTTP
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/statusParâmetros de caminho
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
integer | Sim | O identificador exclusivo da tarefa de tradução de conteúdo a ser verificada. |
Respostas
Resposta de sucesso
{
"status": "completed",
"completeness": 100
}Esquema da resposta
| Campo | Tipo | Descrição |
|---|---|---|
status |
string | O status da tradução atual. Os possíveis valores de status incluem: queued, in_progress, completed, failed, status_unknown. |
completeness |
number | A porcentagem de strings traduzidas (0–100). Calculada como (completed_translatable_strings / total_translatable_strings) × 100. |
Valores de status
| Status | Descrição |
|---|---|
queued |
A tradução foi colocada na fila e está aguardando para ser processada. |
in_progress |
A tradução está sendo processada no momento. |
completed |
A tradução foi concluída com sucesso. |
failed |
A tradução falhou devido a um erro. |
status_unknown |
O status da tradução é desconhecido ou ainda não pode ser determinado. |
Respostas de erro
Causas possíveis:
- Nenhuma tradução de conteúdo existe com o ID especificado
- A tarefa de tradução não pertence ao projeto autenticado
Exemplo
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
-H "Authorization: Bearer YOUR_API_TOKEN"Resposta:
{
"status": "completed",
"completeness": 100
}Resposta enquanto a tarefa ainda está em execução:
{
"status": "in_progress",
"completeness": 70
}{
"status": "completed",
"completeness": 100
}