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

Этот API предоставляет два эндпоинта для работы со строками переводов в плагине TranslatePress. Базовый язык — английский (en_us). Todas as solicitações exigem autorização por meio de um 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 de strings para tradução (GET /keys)

Este endpoint retorna uma lista de strings do dicionário TranslatePress para o idioma especificado. Cada string inclui 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 (mais recentes no topo). Datas, created_at e updated_at sempre null (não são solicitados em SQL).

Parâmetros da solicitação

Parâmetro,	Tipo	Obrigatório	Descrição	Valor padrão
lang	string	Sim	Код языка (например, de para alemão, fr para francês). Os 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
updated_since	string	Não	Фильтр по дате обновления (ISO8601, например, 2025-10-01T00:00:00Z). Retorna apenas as linhas atualizadas após esta data.	—

Cabeçalhos

• Authorization: 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": "Hallo Welt",
      "status": 2,
      "created_at": null,
      "updated_at": null
    },
    {
      "key_id": "dictionary:124",
      "original": "Welcome",
      "translated": "",
      "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
key_id	string	ID exclusivo 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.
created_at	string	Data de criação (ISO8601, null — não solicitado).
updated_at	string	Дата последнего обновления (ISO8601, null — não solicitado).

Metadados (meta)

• total_count: Número total de linhas (considerando os filtros).
• página: Página atual.
• limite: Limite por página.
• page_count=: Número total de páginas.
• próxima_página: URL следующей страницы (null, se for a última).

Erros

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

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

Este endpoint atualiza as traduções de várias strings de uma só vez (lote). É passado um array de objetos com o ID da string, o idioma e a nova tradução. Atualiza o status para "traduzido" (2) e o campo, updated_at.

Corpo da solicitação (JSON)

Array traduções com objetos:

{
  "translations": [
    {
      "key_id": "dictionary:123",
      "language_iso": "de",
      "translation": "Hallo Welt"
    },
    {
      "key_id": "dictionary:124",
      "language_iso": "de",
      "translation": "Willkommen"
    }
  ]
}

Configurações

Campo no objeto,	Tipo	Obrigatório	Descrição
key_id	string	Sim	ID da linha: dicionário:{id} (de GET /keys).
language_iso	string	Sim	Código de idioma (de → de_de, normalizado automaticamente).
Tradução	string	Sim	Новый текст перевода (сохраняется как есть).

Cabeçalhos

• Authorization: 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": "Hallo Welt"
      }
    ]
  }'

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": "Key not found in database"
    }
  ]
}

Descrição dos campos na resposta

• traduções: Matriz de traduções atualizadas com sucesso (retorna os dados de entrada + modified_at em ISO8601).
• erros (opcional, se houver falhas): Matriz de erros.
  • índice: Índice do elemento na matriz de origem.
  • key_id: ID da linha problemática (se aplicável).
  • erro: Texto do 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: Неверные данные (пустой/не-массив traduções, ausência de campos).
• 401/403: Problemas de autorização.
• 404: Idioma ou chave não encontrado (tabela/registro ausente).

Idiomas compatíveis

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

• en → en_us
• ar → ar
• id → id_id
• ko → ko_kr
• tr → tr_tr
• vi → vi
• ru → ru_ru
• fr → fr_fr
• de → de_de
• it → it_it
• ja → ja
• pt → pt_pt
• zh → zh_cn
• es → es_es

Obtenção do token

• No painel de administração do WordPress: Menu, Sincronização de TP → Botão "Gerar novo token" (token de 32 caracteres, gerado automaticamente na primeira inicialização).
• O token é armazenado na opção, tp_sync_api_token.