Documentação da API para integração de traduções TranslatePress (TP Sync API)

Esta API fornece dois endpoints para trabalhar com strings de tradução no plugin TranslatePress. O idioma base é o inglês (en_us). Todas as solicitações exigem autorização via token Bearer (obtido no admin do WordPress no menu "TP Sync").

URL base: https://your-site.com/wp-json/tp-sync/v1/

1. Obtenção das linhas para tradução (GET /keys)

Este endpoint retorna uma lista de strings do dicionário TranslatePress para o idioma especificado. Cada string inclui um ID (no formato dicionário: {id}), texto original em inglês, tradução atual, status e metadados de paginação. Ordenação por ID DESC (os mais novos no topo). Datas, criado em e atualizado em sempre null (não são solicitados no SQL).

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Valor padrão
lang	string	Sim	Código do idioma (por exemplo, de para o alemão fr para o francês). Códigos curtos são normalizados (de → de_de).	—
página	inteiro	Não	Número da página para paginação.	1
limite	inteiro	Não	Número de linhas por página (mínimo 1, máximo 500).	100
atualizado desde	string	Não	Filtro por data de atualização (ISO8601, por exemplo,) 2025-10-01T00:00:00Z). Retorna apenas as linhas atualizadas após esta data.	—

Títulos

• Autorização: Bearer {токен} (obrigatório)

Exemplo de solicitação (cURL)

curl -X GET "https://your-site.com/wp-json/tp-sync/v1/keys?lang=de&page=1&limit=50&updated_since=2025-10-01T00:00:00Z" \
  -H "Authorization: Bearer your-api-token-here"

Exemplo de resposta (JSON)

{
  "keys": [
    {
      "key_id": "dictionary:123",
      "original": "Hello World",
      "translated": "Olá Mundo",
      "status": 2,
      "created_at": null,
      "updated_at": null
    },
    {
      "key_id": "dictionary:124",
      "original": "Welcome",
      "translated": "Bem-vindo",
      "status": 0,
      "created_at": null,
      "updated_at": null
    }
  ],
  "meta": {
    "total_count": 150,
    "page": 1,
    "limit": 50,
    "page_count": 3,
    "next_page": "https://your-site.com/wp-json/tp-sync/v1/keys?lang=de&page=2&limit=50&updated_since=2025-10-01T00:00:00Z"
  }
}

Descrição dos campos na resposta

Campo	Tipo	Descrição
chave_id	string	ID único da linha: dicionário: {id} (id — número do registro na tabela wp_trp_dictionary_en_us_{lang}).
original	string	Texto original em inglês.
traduzido	string	Tradução atual para o idioma especificado (pode estar vazia).
status	inteiro	Status: 0 — não traduzido, 1 — em andamento, 2 — traduzido.
criado em	string	Data de criação (ISO8601 null — não solicitado).
atualizado em	string	Data da última atualização (ISO8601 null — não solicitado).

Metadadosmeta)

• total_countNúmero total de linhas (incluindo filtros).
• páginaPágina atual.
• limiteLimite por página.
• número de páginasNúmero total de páginas.
• próxima página: URL da próxima páginanull, se for a última).

Erros

• 401: Cabeçalho Authorization ausente ou incorreto.
• 403: Token inválido.
• 404: Idioma não encontrado no TranslatePress (tabela ausente).

2. Atualização de traduções (POST /translations)

Este endpoint atualiza traduções para várias linhas de uma vez (lote). É passado um array de objetos com o ID da linha, idioma e nova tradução. Atualiza o status para "traduzido" (2) e o campo atualizado em.

Corpo da solicitação (JSON)

Array traduções com objetos:

{
  "translations": [
    {
      "key_id": "dictionary:123",
      "language_iso": "de",
      "translation": "Olá Mundo"
    },
    {
      "key_id": "dictionary:124",
      "language_iso": "de",
      "translation": "Bem-vindo"
    }
  ]
}

Parâmetros

Campo no objeto	Tipo	Obrigatório	Descrição
chave_id	string	Sim	ID da linha: dicionário: {id} (do GET /keys).
código_iso_idioma	string	Sim	Código do idioma (de → de_de, normalizado automaticamente).
tradução	string	Sim	Novo texto de tradução (mantido como está).

Títulos

• Autorização: Bearer {токен} (obrigatório)
• Content-Type: application/json (obrigatório)

Exemplo de solicitação (cURL)

curl -X POST "https://your-site.com/wp-json/tp-sync/v1/translations" \
  -H "Authorization: Bearer your-api-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "translations": [
      {
        "key_id": "dictionary:123",
        "language_iso": "de",
        "translation": "Olá Mundo"
      }
    ]
  }'

Exemplo de resposta (JSON)

{
  "translations": [
    {
      "key_id": "dictionary:123",
      "language_iso": "de",
      "translation": "Hallo Welt",
      "modified_at": "2025-10-15T12:00:00Z"
    }
  ],
  "errors": [
    {
      "index": 1,
      "key_id": "dictionary:999",
      "error": "Chave não encontrada no banco de dados"
    }
  ]
}

Descrição dos campos na resposta

• traduçõesArray de traduções atualizadas com sucesso (retorna os dados de entrada + modificado em em ISO8601).
• erros (opcional, se houver falhas): Matriz de erros.
  • índiceÍndice do elemento no array original.
  • chave_id: ID da linha problemática (se aplicável).
  • erroTexto de erro (exemplos: "Campos obrigatórios ausentes", "Formato de key_id inválido. Esperado: dictionary:{id}", "Idioma não encontrado", "Chave não encontrada no banco de dados", "Falha na atualização do banco de dados").

Erros

• 400: Dados inválidos (vazio/não é um array) traduções, ausência de campos).
• 401/403: Problemas de autorização.
• 404: Idioma ou chave não encontrada (tabela/registro ausente).

Idiomas suportados

Códigos curtos são automaticamente normalizados (com base no mapeamento no código). Para os desconhecidos: {code}_{code} (por exemplo, pl → pl_pl).

• en → en_us
• para
• id → id_id
• ko → ko_kr
• tr → tr_tr
• vi → vi
• ru → ru_ru
• fr → fr_fr
• de → de_de
• isso
• para
• pt → pt_pt
• zh → zh_cn
• es → es_es

Obtenção do token

• No painel administrativo do WordPress: Menu Sincronização TP → Botão "Generate New Token" (token de 32 caracteres, gerado automaticamente na primeira execução).
• O token é armazenado na opção token_api_de_sync_tp.