PTC

Enviar e gerenciar arquivos de origem via API

Use esta API para enviar novos arquivos de origem, substituir os desatualizados, acompanhar o progresso da tradução e baixar as traduções concluídas.

Seja gerenciando um único arquivo ou automatizando um fluxo de localização contínua, esta API oferece controle total sobre o conteúdo que você envia para tradução e como você recebe as traduções.

Como a API da PTC identifica e organiza os arquivos de origem

A API da PTC usa um sistema flexível baseado em tags de arquivo e caminhos de arquivo. Esses parâmetros trabalham juntos para garantir que cada arquivo que você envia, atualiza ou solicita seja claramente definido e fácil de gerenciar.

Tags de arquivo

As tags de arquivo são uma maneira flexível de agrupar e organizar arquivos de origem em projetos de tradução. Você pode usá-las como categorias para atender às necessidades do seu fluxo de trabalho. Por exemplo, as tags de arquivo podem indicar:

  • Controle de versão: v1.0, beta, production
  • Branches de recursos: user-auth, dashboard-redesign
  • Contexto do aplicativo: mobile-app, admin-panel, marketing
  • Propriedade da equipe: frontend-team, content-team
  • Estado do fluxo de trabalho: approved, pending-review, priority-high

Os nomes das tags de arquivo são opcionais na maioria das operações da API. No entanto, todo arquivo de origem sempre tem pelo menos uma tag. Uma tag de arquivo padrão é criada e atribuída automaticamente quando um projeto é configurado. Esse comportamento padrão mantém os projetos organizados mesmo em configurações simples, ao mesmo tempo que permite construir estruturas de tags mais avançadas quando necessário.

Nome da tag de arquivo + Caminho do arquivo

Cada arquivo de origem é identificado de forma exclusiva pela combinação de seu nome da tag de arquivo e caminho do arquivo.

  • Se você não fornecer uma tag de arquivo personalizada ao enviar ou processar um arquivo, a tag padrão será atribuída automaticamente.
  • O nome da tag + caminho de um arquivo definem juntos sua identidade. Essa combinação garante que cada arquivo seja único dentro do seu projeto, mesmo que diferentes versões ou contextos compartilhem o mesmo caminho de arquivo.

Parâmetros de consulta

Ao recuperar um arquivo específico, os endpoints relacionados podem aceitar parâmetros de consulta como:

  • file_tag_name – A tag associada ao arquivo
  • file_path – O caminho para o arquivo

Esses parâmetros permitem que você localize e recupere com precisão os arquivos corretos do seu projeto.


Listar todos os arquivos de origem no projeto

Lista todos os arquivos de origem no seu projeto, com opções para filtrar, classificar e paginar os resultados. Isso é útil quando você deseja navegar pelos seus arquivos, verificar o status deles ou encontrar arquivos específicos com base na tag, caminho ou método de envio.

Requisição HTTP

GET https://app.ptc.wpml.org/api/v1/source_files

Parâmetros

Parâmetro Tipo Obrigatório Padrão Descrição
page inteiro Não 1 O número da página para paginação. Deve ser maior que 0.
per_page inteiro Não 50 O número de itens por página. Deve ser maior que 0.
order_by string Não created_at O campo pelo qual classificar. Valores permitidos: id, created_at, updated_at.
sort string Não desc A direção da classificação. Valores permitidos: asc, desc.
file_path string Não Filtra pelo caminho do arquivo exato.
upload_origin string Não Filtra pela forma como o arquivo foi enviado. Os valores permitidos incluem: git, manual, api.

Respostas

Resposta de sucesso

200 OKapplication/json
{
  "source_files": [
    {
      "id": 123,
      "file_path": "locales/en.po",
      "translation_path": "locales/{{lang}}.po",
      "additional_translation_files": ["locales/{{lang}}.mo"],
      "status": "completed",
      "upload_origin": "git",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T14:20:00.000Z",
      "file_tag": {
        "id": 456,
        "name": "frontend"
      },
      "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3,
    "has_next_page": true,
    "has_previous_page": false
  }
}
Esquema de resposta

Objeto do arquivo de origem:

Campo Tipo Descrição
id inteiro O identificador exclusivo do arquivo de origem.
file_path string O caminho para o arquivo de origem dentro do projeto.
translation_path string O padrão de onde os arquivos traduzidos devem ser salvos.
additional_translation_files array[string] Os caminhos para quaisquer arquivos de saída adicionais.
status string O status de processamento atual do arquivo de origem.
upload_origin string Como o arquivo foi enviado (git, manual, api).
created_at string Um timestamp ISO 8601 indicando quando o arquivo de origem foi criado originalmente.
updated_at string Um timestamp ISO 8601 indicando quando o arquivo de origem foi atualizado pela última vez.
file_tag objeto Informações sobre a tag de arquivo.
file_tag.id inteiro O identificador da tag de arquivo.
file_tag.name string O nome da tag de arquivo.
download_url string A URL para baixar as traduções deste arquivo de origem.

Objeto de paginação:

Campo Tipo Descrição
page inteiro O número da página atual.
per_page inteiro O número de itens por página.
total inteiro O número total de arquivos de origem.
total_pages inteiro O número total de páginas.
has_next_page booleano Se há uma próxima página disponível.
has_previous_page booleano Se há uma página anterior disponível.

Respostas de erro

Não autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parâmetros inválidos
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Exemplos de requisição

Requisição básica:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Requisição filtrada:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25&order_by=updated_at&sort=desc" \
  -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/source_files?file_tag_name=frontend&page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Obter strings de tradução

Recupera todas as strings traduzíveis de um arquivo de origem específico, junto com suas traduções existentes em todos os idiomas de destino.

Este endpoint é útil para buscar conteúdo que precisa ser traduzido ou que já foi traduzido. O arquivo de origem é identificado por file_path e file_tag_name.

Requisição HTTP

GET https://app.ptc.wpml.org/api/v1/source_files/translation_strings

Parâmetros

Parâmetro Tipo Obrigatório Padrão Descrição
file_path string Sim O caminho para o arquivo de origem dentro do projeto.
file_tag_name string Não O nome da tag de arquivo. Se não for fornecido, a tag padrão do projeto será usada.
page inteiro Não 1 O número da página para paginação (usado como um Cursor). Deve ser maior que 0.
q string Não A consulta de pesquisa para filtrar as strings de tradução pelo seu texto de origem.

Respostas

Resposta de sucesso

200 OKapplication/json
{
  "total_strings_count": 1250,
  "translation_strings": [
    {
      "source": "Welcome to our application",
      "translations": {
        "es": "Bienvenido a nuestra aplicación",
        "fr": "Bienvenue dans notre application",
        "de": "Willkommen in unserer Anwendung"
      }
    },
    {
      "source": "Login",
      "translations": {
        "es": "Iniciar sesión",
        "fr": "Connexion",
        "de": "Anmelden"
      }
    }
  ],
  "cursor": 1
}
Esquema de resposta
Campo Tipo Descrição
total_strings_count inteiro O número total de strings traduzíveis no arquivo de origem.
translation_strings array[objeto] O array de objetos de string de tradução (paginado, máximo de 500 por página).
translation_strings[].source string O texto de origem original a ser traduzido.
translation_strings[].translations objeto Um hash de traduções onde as chaves são códigos ISO de idioma e os valores são o texto traduzido.
cursor inteiro O Cursor da página atual usado para paginação.

Respostas de erro

Arquivo de origem não encontrado
404 Not Found
{
  "error": "Source file not found"
}
Não autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parâmetros inválidos
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Exemplos de requisição

Requisição básica:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Uma requisição com tag de arquivo:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Uma requisição com paginação e pesquisa:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend&page=2&q=welcome" \
  -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/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend&page=1&q=login" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Criar o arquivo de origem

Registra um novo arquivo de origem no seu projeto para que ele fique pronto para tradução.

Este endpoint cria a entrada do arquivo e configura sua tradução, mas não anexa o conteúdo real do arquivo.

Após criar o arquivo, você precisará usar o endpoint Processar o arquivo de origem para enviar o conteúdo e iniciar o processo de tradução.

Requisição HTTP

POST https://app.ptc.wpml.org/api/v1/source_files

Parâmetros

Parâmetro Tipo Obrigatório Descrição
file_path string Sim O caminho onde o arquivo de origem deve ser armazenado no projeto. Deve ter uma extensão suportada.
output_file_path string Sim O padrão de caminho de saída para os arquivos traduzidos. Use {{lang}} como um placeholder para o código do idioma.
translations array[objeto] Não Os arquivos de tradução pré-existentes para enviar junto com o arquivo de origem. Esses arquivos serão armazenados conforme fornecidos, e suas strings não serão retraduzidas pela PTC. Observe que fornecer traduções existentes não é recomendado, pois a PTC produz resultados melhores quando pode usar o contexto completo do seu projeto e traduzir do zero.
translations[].target_language_iso string Sim O código ISO do idioma de destino para esta tradução. Você pode encontrar a lista completa de idiomas suportados e seus códigos ISO no endpoint Listar todos os idiomas de destino.
translations[].file arquivo Sim O arquivo de tradução a ser enviado.
additional_translation_files array[objeto] Não Configurações de arquivos de saída adicionais para formatos específicos. Para ver quais formatos suportam arquivos de saída adicionais, consulte o endpoint Listar formatos de arquivo suportados. Para formatos não suportados, este campo será ignorado.
additional_translation_files[].type string Sim Veja formatos de arquivo suportados para mais detalhes.
additional_translation_files[].path string Sim O padrão de caminho para o arquivo.

Respostas

Resposta de sucesso

201 Createdapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
Esquema de resposta
Campo Tipo Descrição
source_file.id inteiro O identificador exclusivo do arquivo de origem criado.
source_file.file_path string O caminho do arquivo de origem dentro do projeto.
source_file.created_at string Um timestamp ISO 8601 indicando quando o arquivo de origem foi criado originalmente.
source_file.file_tag.id inteiro O identificador da tag de arquivo.
source_file.file_tag.name string O nome da tag de arquivo.

Respostas de erro

Falha na validação
422 Unprocessable Entity
{
  "success": false,
  "error": "Source file creation failed"
}
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

Criação básica de arquivo de origem:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{{lang}}.json" \
  -F "file_tag_name=frontend"

Requisição com URL de callback:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/messages.po" \
  -F "output_file_path=locales/{{lang}}/messages.po" \
  -F "callback_url=https://your-app.com/webhooks/translation-complete"

Requisição com traduções pré-existentes:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/messages.json" \
  -F "output_file_path=locales/{{lang}}/messages.json" \
  -F "translations[0][target_language_iso]=es" \
  -F "translations[0][file]=@spanish_translations.json" \
  -F "translations[1][target_language_iso]=fr" \
  -F "translations[1][file]=@french_translations.json"

Requisição com arquivos de saída adicionais:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/messages.po" \
  -F "output_file_path=locales/{{lang}}/messages.po" \
  -F "additional_translation_files[][type]=mo" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.mo" \
  -F "additional_translation_files[][type]=json" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.json"

Exemplos de código

  • JavaScript (FormData)
  • Python (requests)
  • PHP (cURL)
  • Node.js (axios)
  • Corpo da requisição de callback
curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{{lang}}.json"
{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "frontend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=src/locales/en.json&file_tag_name=frontend",
  "file_path": "src/locales/en.json"
}

Processar o arquivo de origem

Envia o conteúdo para um arquivo de origem existente e inicia o processo de tradução.

Este endpoint substitui o conteúdo atual do arquivo, atualiza as strings traduzíveis armazenadas e inicia a tradução automática.

Para usar este endpoint, o arquivo de origem já deve existir no projeto. Se você ainda não o criou, veja Criar o arquivo de origem.

Requisição HTTP

PUT https://app.ptc.wpml.org/api/v1/source_files/process

Parâmetros

Parâmetro Tipo Obrigatório Descrição
file arquivo Sim O arquivo de origem a ser enviado. O conteúdo do arquivo é validado para garantir que corresponda à extensão declarada. Por exemplo, se a extensão do arquivo for .json, o conteúdo enviado deve ser um JSON válido.
file_path string Sim O caminho para o arquivo de origem existente no projeto que deve ser atualizado.
file_tag_name string Não O nome da tag de arquivo associada ao arquivo de origem. Se não for fornecido, a tag de arquivo padrão do projeto será usada.
callback_url string Não A URL que recebe notificações de webhook quando o processamento do arquivo for concluído.

Respostas

Resposta de sucesso

200 OKapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
Esquema de resposta
Campo Tipo Descrição
source_file.id inteiro O identificador exclusivo do arquivo de origem processado.
source_file.file_path string O caminho do arquivo de origem dentro do projeto.
source_file.created_at string Um timestamp ISO 8601 indicando quando o arquivo de origem foi criado originalmente.
source_file.file_tag.id inteiro O identificador da tag de arquivo.
source_file.file_tag.name string O nome da tag de arquivo.

Respostas de erro

Arquivo de origem não encontrado
422 Unprocessable Entity
{
  "errors": {
    "file": ["File format is invalid or not supported"]
  }
}
Não autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Fluxo de trabalho

  1. Pré-requisito: O arquivo de origem já deve ter sido criado via Criar o arquivo de origem.
  2. Envio de arquivo: O novo conteúdo é enviado e substitui o conteúdo existente do arquivo.
  3. Processamento: As novas strings traduzíveis são extraídas e traduzidas automaticamente.
  4. Callback: Uma notificação de webhook opcional é enviada quando o processamento termina.

Callback de webhook

Quando uma callback_url é fornecida, a PTC enviará uma requisição POST para essa URL quando o processamento for concluído.

Corpo da requisição de callback:

{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "frontend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=src/locales/en.json&file_tag_name=frontend",
  "file_path": "src/locales/en.json"
}

Exemplos de requisição

Processamento básico de arquivo:

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend"

Requisição com URL de callback:

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@messages.po" \
  -F "file_path=locales/messages.po" \
  -F "callback_url=https://your-app.com/webhooks/translation-complete"

Exemplos de código

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend" \
  -F "callback_url=https://your-app.com/webhooks/complete"

Formatos de arquivo suportados

O endpoint suporta vários formatos de arquivo traduzíveis, incluindo arquivos JSON, PO/POT, XLIFF e Properties, entre outros. A validação do formato de arquivo ocorre durante o envio para garantir a compatibilidade.

Use o endpoint Listar formatos de arquivo suportados para obter a lista completa de formatos suportados.


Obter o status da tradução

Recupera o progresso atual da tradução de um arquivo de origem específico, incluindo quanto foi concluído e seu status geral de processamento.

Isso é útil para:

  • Monitoramento de progresso – Acompanhar o progresso da tradução para tarefas de longa duração
  • Atualizações de UI – Exibir porcentagens de conclusão no seu aplicativo
  • Integração de fluxo de trabalho – Acionar ações quando a tradução atingir um limite definido

Requisição HTTP

GET https://app.ptc.wpml.org/api/v1/source_files/translation_status

Parâmetros

Parâmetro Tipo Obrigatório Descrição
file_path string Sim O caminho para o arquivo de origem dentro do projeto.
file_tag_name string Não O nome da tag de arquivo. Se não for fornecido, a tag de arquivo padrão do projeto será usada.

Respostas

Resposta de sucesso

200 OKapplication/json
{
  "translation_status": {
    "status": "completed",
    "completeness": 100
  }
}
Esquema de resposta
Campo Tipo Descrição
translation_status.status string O status de processamento atual do arquivo de origem. Veja os valores de status abaixo.
translation_status.completeness número A porcentagem de strings traduzidas (0–100). Calculada como (completed_translatable_strings / total_translatable_strings) × 100.

Valores de status

O campo status pode conter os seguintes valores:

Status Descrição
pending O arquivo de origem está aguardando para ser processado.
processing A tradução está em andamento.
completed Todas as traduções foram concluídas.
failed O processo de tradução encontrou erros.

Respostas de erro

Arquivo de origem não encontrado
404 Not Found
{
  "error": "Source file not found"
}
Não autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parâmetros inválidos
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Exemplos de requisição

Requisição básica:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Requisição com tag de arquivo:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po&file_tag_name=frontend" \
  -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/source_files/translation_status?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Baixar todas as traduções

Baixa todos os arquivos traduzidos de um arquivo de origem específico como um arquivo ZIP.

Este endpoint cria e retorna um arquivo ZIP contendo todos os arquivos de tradução nos idiomas de destino para o arquivo de origem especificado.

Se nenhuma tradução estiver disponível para o arquivo, a requisição retornará um erro 404 Not Found.

Requisição HTTP

GET https://app.ptc.wpml.org/api/v1/source_files/download_translations

Parâmetros

Parâmetro Tipo Obrigatório Descrição
file_path string Sim O caminho para o arquivo de origem dentro do projeto.
file_tag_name string Não O nome da tag de arquivo. Se não for fornecido, a tag de arquivo padrão do projeto será usada. Um arquivo de origem é identificado de forma exclusiva pela combinação de file_path e file_tag_name.

Respostas

Resposta de sucesso

200 OKapplication/zip202 AcceptedRetry-After: 30
{
  "status": "processing",
  "message": "Translations are still in progress. Please retry after the specified delay.",
  "retry_after": 30
}

A PTC processa as traduções de forma assíncrona. Geralmente, há uma breve espera entre o envio de um arquivo de origem e a disponibilidade das traduções para download.

Quando isso acontecer, aguarde o número de segundos especificado em Retry-After.

Respostas de erro

Arquivo de origem não encontrado
404 Not Found
{
  "error": "Source file not found"
}
Nenhuma tradução disponível
404 Not Found
{
  "error": "No translations are available for this source file"
}
Não autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parâmetros inválidos
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Exemplos de requisição

Requisição básica:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -o translations.zip

Requisição com tag de arquivo:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -o frontend-translations.zip

Exemplos de código

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o translations.zip
# 200 -> saves the zip; 202 -> {"status":"processing","retry_after":N} (retry later);
# 404 -> {"error":"No translations are available for this source file"}

Enviar arquivos de origem em lote

Envia um arquivo ZIP contendo vários arquivos traduzíveis. Cada arquivo no arquivo ZIP é extraído, validado e processado. Os formatos suportados são identificados automaticamente.

Esta é a versão em lote de Processar o arquivo de origem, projetada para acelerar atualizações em grande escala.

Informações adicionais

  • Se um arquivo corresponder a um arquivo de origem existente, ele será atualizado com o novo conteúdo, e as traduções serão acionadas novamente.
  • Se um arquivo for suportado, mas não corresponder a nenhum arquivo de origem existente, ele será adicionado à lista not_found_files e ignorado.
  • Arquivos com formatos não suportados são listados em unsupported_files e ignorados.
  • Arquivos com conteúdo inválido também são listados em unsupported_files e ignorados.
  • Arquivos ZIP grandes podem levar mais tempo para serem processados. Os arquivos são processados um por um para gerenciar os recursos, por isso é melhor dividir envios muito grandes (mais de 100 arquivos) em lotes menores. Todos os arquivos no arquivo ZIP são configurados para tradução automática.
  • O arquivo ZIP enviado deve ser válido e legível. Todos os arquivos dentro dele devem estar em um formato suportado. Os nomes dos arquivos não devem incluir caracteres especiais que possam causar problemas de caminho.
  • Se uma callback_url for fornecida, uma requisição POST será enviada para cada arquivo de origem processado com seus resultados.

Requisição HTTP

POST https://app.ptc.wpml.org/api/v1/source_files/bulk

Parâmetros

Parâmetro Tipo Obrigatório Descrição
zip_file arquivo Sim Um arquivo ZIP contendo os arquivos de origem a serem enviados. Deve ser um arquivo ZIP válido.
file_tag_name string Não O nome da tag de arquivo para associar a todos os arquivos de origem no arquivo ZIP. Se não for especificado, a tag de arquivo padrão do projeto será usada. Cada arquivo de origem é identificado de forma exclusiva pela combinação de file_path e file_tag_name.
callback_url string Não A URL que recebe notificações de webhook quando cada arquivo for processado.

Estrutura esperada do arquivo ZIP

O arquivo ZIP pode conter arquivos de origem em qualquer estrutura de diretório. A estrutura de diretório é preservada, e os arquivos são processados recursivamente.

Exemplo de estrutura do ZIP:

source-files.zip
├── locales/
│   ├── messages-en.po
│   ├── validation-en.po
│   └── admin-en.po
├── frontend/
│   ├── components-en.json
│   └── pages-en.json
│   └── not-found-en.json
├── app-strings-en.properties
└── readme.txt (will be ignored)

Tipos de arquivo suportados:

  • JSON: arquivos .json
  • Gettext: arquivos .po, .pot
  • Properties: arquivos .properties
  • YAML: arquivos .yml, .yaml
  • XML: arquivos .xml
  • Strings: arquivos .strings
  • XLIFF: arquivos .xliff, .xlf
  • CSV: arquivos .csv
  • PHP: arquivos .php

Respostas

Resposta de sucesso

200 OKapplication/json
{
  "success": true,
  "file_tag": {
      "id": 456,
      "name": "backend"
  },
  "processed_files": [
    {
      "id": 123,
      "file_path": "locales/messages-en.po",
      "created_at": "2024-01-15T10:30:00.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    },
    {
      "id": 124,
      "file_path": "locales/validation-en.po",
      "created_at": "2024-01-15T10:30:05.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    }
  ],
  "unsupported_files": [
    "readme.txt",
    "config.ini"
  ],
  "not_found_files": ["frontend/not-found-en.json"]
}
Esquema de resposta
Campo Tipo Descrição
success booleano Se a operação de envio em lote foi bem-sucedida.
file_tag objeto As informações da tag de arquivo.
file_tag.id inteiro O identificador da tag de arquivo.
file_tag.name string O nome da tag de arquivo.
processed_files array[objeto] Um array de arquivos de origem que foram processados com sucesso.
processed_files[].id inteiro O identificador exclusivo do arquivo de origem criado.
processed_files[].file_path string O caminho do arquivo de origem, preservando a estrutura original do ZIP.
processed_files[].created_at string Um timestamp ISO 8601 indicando quando o arquivo de origem foi criado.
processed_files[].file_tag objeto As informações da tag de arquivo.
processed_files[].file_tag.id inteiro O identificador da tag de arquivo.
processed_files[].file_tag.name string O nome da tag de arquivo.
unsupported_files array[string] Um array de nomes de arquivos que não estão em um formato suportado.
not_found_files array[string] Um array de arquivos suportados que não corresponderam a nenhum arquivo de origem existente e foram ignorados.

Respostas de erro

Arquivo ZIP inválido

422 Unprocessable Entity
{
  "success": false,
  "error": "File format is invalid",
  "processed_files": [],
  "unsupported_files": []
}

Falha no processamento

422 Unprocessable Entity
{
  "success": false,
  "error": "Failed to process ZIP archive",
  "processed_files": [],
  "unsupported_files": []
}

Não autorizado

401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}

Proibido

403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Callback de webhook

Quando uma callback_url é fornecida, uma requisição POST é enviada para cada arquivo processado.

Corpo da requisição de callback (por arquivo):

{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "backend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/messages-en.po&file_tag_name=backend",
  "file_path": "locales/messages-en.po"
}

Exemplos de requisição

Envio em lote básico:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend"

Requisição com URL de callback:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@translations.zip" \
  -F "file_tag_name=localization" \
  -F "callback_url=https://your-app.com/webhooks/bulk-complete"

Exemplos de código

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend" \
  -F "callback_url=https://your-app.com/webhooks/complete"
Próximo:

Encontrar formatos de arquivo e idiomas de destino suportados via API →