PTC

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.

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_translation

Parâ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

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 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
422 Unprocessable Entity
{
  "errors": {
    "data": ["Data must be a valid JSON object"]
  }
}
Idiomas de destino inválidos
422 Unprocessable Entity
{
  "errors": {
    "target_languages": ["Language codes [zh, xx] are not configured for this project"]
  }
}
Não autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibido
403 Forbidden
{
  "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” → É traduzido
  • user.settings.theme: “Choose Theme” → É traduzido
  • user.settings.count: 5 → Permanece inalterado
  • user.settings.enabled: true → Permanece inalterado

Fluxo de trabalho de tradução

  1. Validação: A estrutura JSON e os idiomas de destino são verificados
  2. Preparação do arquivo de origem: O JSON é convertido para um formato de origem interno
  3. 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
  4. Enfileiramento de tarefas: Uma tarefa é colocada na fila para cada idioma de destino
  5. Processamento: A tradução automática é executada nas strings extraídas
  6. Callback (opcional): Um webhook é enviado quando todas as traduções são concluídas, se a callback_url for 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"

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

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 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
404 Not Found
{
  "error": "Content translation not found"
}
Não autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibido
403 Forbidden
{
  "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"

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}/status

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 verificada.

Respostas

Resposta de sucesso

200 OKapplication/json
{
  "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

404 Not Found

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
}