Documentación de la API para la integración de traducciones de TranslatePress (TP Sync API)

Этот API предоставляет два эндпоинта для работы со строками переводов в плагине TranslatePress. Базовый язык — английский (en_us). Todas las solicitudes requieren autorización mediante un token Bearer (se obtiene en el panel de administración de WordPress en el menú "TP Sync").

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

1. Obtención de cadenas para traducir (GET /keys)

Este endpoint devuelve una lista de cadenas del diccionario de TranslatePress para el idioma especificado. Cada cadena incluye ID (en el formato, diccionario:{id}), texto original en inglés, traducción actual, estado y metadatos de paginación. Ordenación por ID DESC (más recientes arriba). Fechas, created_at y updated_at siempre null (no se solicitan en SQL).

Parámetros de la solicitud

Parámetro,	Tipo	Obligatorio	Descripción	Valor predeterminado
lang	cadena	Sí	Код языка (например, de para alemán, fr para francés). Los códigos cortos se normalizan (de → de_de).	—
página	entero	No	Número de página para la paginación.	1
límite	entero	No	Número de filas por página (mínimo 1, máximo 500).	100
updated_since	cadena	No	Фильтр по дате обновления (ISO8601, например, 2025-10-01T00:00:00Z). Devuelve solo las filas actualizadas después de esta fecha.	—

Encabezados

• Authorization: Bearer {токен} (obligatorio)

Ejemplo de solicitud (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"

Ejemplo de respuesta (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"
  }
}

Descripción de los campos en la respuesta

Campo	Tipo	Descripción
key_id	cadena	ID único de fila: diccionario:{id} id — número de registro en la tabla wp_trp_dictionary_en_us_{lang}).
original	cadena	Texto original en inglés.
traducido	cadena	Traducción actual para el idioma especificado (puede estar vacía).
estado	entero	Estado: 0 — sin traducir, 1 — en curso, 2 — traducido.
created_at	cadena	Fecha de creación (ISO8601, null — no se solicita).
updated_at	cadena	Дата последнего обновления (ISO8601, null — no se solicita).

Metadatos (meta)

• total_count: Número total de filas (teniendo en cuenta los filtros).
• página: Página actual.
• límite: Límite por página.
• page_count=: Número total de páginas.
• página_siguiente: URL следующей страницы (null, si es la última).

Errores

• 401: Encabezado Authorization ausente o no válido.
• 403: Token no válido.
• 404: Idioma no encontrado en TranslatePress (falta la tabla).

2. Actualización de traducciones (POST /translations)

Este endpoint actualiza las traducciones de varias cadenas a la vez (lote). Se pasa una matriz de objetos con el ID de la cadena, el idioma y la nueva traducción. Actualiza el estado a "traducido" (2) y el campo, updated_at.

Cuerpo de la solicitud (JSON)

Matriz traducciones con objetos:

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

Configuración

Campo en el objeto,	Tipo	Obligatorio	Descripción
key_id	cadena	Sí	ID de fila: diccionario:{id} (de GET /keys).
language_iso	cadena	Sí	Código de idioma (de → de_de, se normaliza automáticamente).
Traducción	cadena	Sí	Новый текст перевода (сохраняется как есть).

Encabezados

• Authorization: Bearer {токен} (obligatorio)
• Content-Type: application/json (obligatorio)

Ejemplo de solicitud (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"
      }
    ]
  }'

Ejemplo de respuesta (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"
    }
  ]
}

Descripción de los campos en la respuesta

• traducciones: Matriz de traducciones actualizadas correctamente (devuelve los datos de entrada + modified_at en ISO8601).
• errores (opcional, si hay fallos): Matriz de errores.
  • índice: Índice del elemento en la matriz de origen.
  • key_id: ID de la fila problemática (si corresponde).
  • error: Texto del error (ejemplos: "Faltan campos obligatorios", "Formato de key_id no válido. Esperado: dictionary:{id}", "Idioma no encontrado", "Clave no encontrada en la base de datos", "Error al actualizar la base de datos").

Errores

• 400: Неверные данные (пустой/не-массив traducciones, ausencia de campos).
• 401/403: Problemas de autorización.
• 404: Idioma o clave no encontrados (tabla/registro ausente).

Idiomas compatibles

Los códigos cortos se normalizan automáticamente (según la asignación en el código). Para los desconocidos:, {code}_{code} (por ejemplo, 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

Obtención del token

• En el panel de administración de WordPress: Menú, Sincronización de TP → Botón "Generar nuevo token" (token de 32 caracteres, se genera automáticamente en el primer inicio).
• El token se almacena en la opción, tp_sync_api_token.