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 e as chaves originais. Ela traduz apenas valores de texto, mantendo números, booleanos, nulos e outros valores não textuais 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 mantém números, booleanos, nulos e outros valores não textuais inalterados.

É 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 for 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 de 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 as 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 o callback_url for fornecido

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ções

Tradução JSON básica:

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 (the create response
# carries a "status" field as well, but it is usually null until the run
# starts, and stays "in_progress" until done):
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 de uma tarefa de tradução de conteúdo específica.

A resposta preserva a sua estrutura de entrada: ela retorna um objeto de origem mais um objeto por idioma de destino (com chaves pelo 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 de resposta

Campo Tipo Descrição
source object O conteúdo de origem original na mesma estrutura aninhada enviada.
{language_code} object O conteúdo traduzido para cada idioma de destino, com chave pelo seu código ISO (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ções

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 de resposta
Campo Tipo Descrição
status string O status atual da tradução. Os possíveis valores de status são: draft, queued, in_progress, completed, failed, out_of_credit e null.
completeness number A porcentagem de strings traduzidas (0–100). Calculada como (completed_translatable_strings / total_translatable_strings) × 100.
Valores de status
Status Descrição
draft O arquivo de origem está registrado, mas ainda não tem nenhum arquivo anexado, portanto, não há nada para traduzir.
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.
out_of_credit A tradução parou porque o projeto ficou sem palavras. Este é um estado final — a execução não é retomada por conta própria assim que mais palavras são adicionadas, portanto, faça a consulta periódica para ele como faria para failed.
null Nenhuma tradução atingiu qualquer um dos status acima ainda. Espere isso logo após criar uma tradução de conteúdo e trate-o como “não iniciado” em vez de um erro.

Respostas de erro

404 Not Found

Possíveis causas:

  • Não existe nenhuma tradução de conteúdo 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
}