PTC

Suba y gestione archivos de origen a través de la API

Utilice esta API para subir nuevos archivos de origen, reemplazar los obsoletos, hacer un seguimiento del progreso de la traducción y descargar las traducciones completadas.

Tanto si gestiona un solo archivo como si automatiza un flujo de trabajo de localización continua, esta API le ofrece un control total sobre el contenido que envía para traducir y cómo recibe las traducciones.

Cómo identifica y organiza los archivos de origen la API de PTC

La API de PTC utiliza un sistema flexible basado en etiquetas de archivo y rutas de archivo. Estos parámetros funcionan en conjunto para garantizar que cada archivo que suba, actualice o solicite esté claramente definido y sea fácil de gestionar.

Etiquetas de archivo

Las etiquetas de archivo son una forma flexible de agrupar y organizar los archivos de origen en los proyectos de traducción. Puede utilizarlas como categorías para adaptarlas a las necesidades de su flujo de trabajo. Por ejemplo, las etiquetas de archivo pueden indicar:

  • Control de versiones: v1.0, beta, production
  • Ramas de características: user-auth, dashboard-redesign
  • Contexto de la aplicación: mobile-app, admin-panel, marketing
  • Propiedad del equipo: frontend-team, content-team
  • Estado del flujo de trabajo: approved, pending-review, priority-high

Los nombres de las etiquetas de archivo son opcionales en la mayoría de las operaciones de la API. Sin embargo, cada archivo de origen siempre tiene al menos una etiqueta. Se crea y asigna automáticamente una etiqueta de archivo predeterminada al configurar un proyecto. Este comportamiento predeterminado mantiene los proyectos organizados incluso en configuraciones sencillas, al tiempo que le permite crear estructuras de etiquetado más avanzadas cuando sea necesario.

Nombre de la etiqueta de archivo + ruta del archivo

Cada archivo de origen se identifica de forma exclusiva mediante la combinación de su nombre de etiqueta de archivo y su ruta de archivo.

  • Si no proporciona una etiqueta de archivo personalizada al subir o procesar un archivo, se asignará la etiqueta predeterminada automáticamente.
  • El nombre de la etiqueta + la ruta de un archivo definen en conjunto su identidad. Esta combinación garantiza que cada archivo sea único dentro de su proyecto, incluso si diferentes versiones o contextos comparten la misma ruta de archivo.

Parámetros de consulta

Al recuperar un archivo específico, los endpoints relacionados pueden aceptar parámetros de consulta como:

  • file_tag_name: la etiqueta asociada al archivo
  • file_path: la ruta del archivo

Estos parámetros le permiten localizar con precisión y recuperar los archivos correctos de su proyecto.


Listar todos los archivos de origen en el proyecto

Enumera todos los archivos de origen de su proyecto, con opciones para filtrar, ordenar y paginar los resultados. Esto resulta útil cuando desea explorar sus archivos, comprobar su estado o encontrar archivos específicos en función de la etiqueta, la ruta o el método de subida.

Petición HTTP

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

Parámetros

Parámetro Tipo Obligatorio Predeterminado Descripción
page entero No 1 El número de página para la paginación. Debe ser mayor que 0.
per_page entero No 50 El número de elementos por página. Debe ser mayor que 0.
order_by cadena No created_at El campo por el cual ordenar. Valores permitidos: id, created_at, updated_at.
sort cadena No desc La dirección de ordenación. Valores permitidos: asc, desc.
file_path cadena No Filtra por la ruta de archivo exacta.
upload_origin cadena No Filtra por la forma en que se subió el archivo. Los valores permitidos incluyen: git, manual, api.

Respuestas

Respuesta de éxito

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 respuesta

Objeto del archivo de origen:

Campo Tipo Descripción
id entero El identificador único del archivo de origen.
file_path cadena La ruta del archivo de origen dentro del proyecto.
translation_path cadena El patrón de dónde deben guardarse los archivos traducidos.
additional_translation_files array[cadena] Las rutas para cualquier archivo de salida adicional.
status cadena El estado de procesamiento actual del archivo de origen.
upload_origin cadena La forma en que se subió el archivo (git, manual, api).
created_at cadena Una marca de tiempo ISO 8601 que indica cuándo se creó originalmente el archivo de origen.
updated_at cadena Una marca de tiempo ISO 8601 que indica cuándo se actualizó por última vez el archivo de origen.
file_tag objeto Información sobre la etiqueta de archivo.
file_tag.id entero El identificador de la etiqueta de archivo.
file_tag.name cadena El nombre de la etiqueta de archivo.
download_url cadena La URL para descargar las traducciones de este archivo de origen.

Objeto de paginación:

Campo Tipo Descripción
page entero El número de página actual.
per_page entero El número de elementos por página.
total entero El número total de archivos de origen.
total_pages entero El número total de páginas.
has_next_page booleano Si hay una página siguiente disponible.
has_previous_page booleano Si hay una página anterior disponible.

Respuestas de error

No autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Prohibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parámetros no válidos
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Peticiones de ejemplo

Petición 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"

Petición 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"

Ejemplos 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"

Obtener cadenas de traducción

Recupera todas las cadenas traducibles de un archivo de origen específico, junto con sus traducciones existentes en todos los idiomas de destino.

Este endpoint es útil para obtener contenido que necesita ser traducido o que ya ha sido traducido. El archivo de origen se identifica mediante file_path y file_tag_name.

Petición HTTP

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

Parámetros

Parámetro Tipo Obligatorio Predeterminado Descripción
file_path cadena La ruta del archivo de origen dentro del proyecto.
file_tag_name cadena No El nombre de la etiqueta de archivo. Si no se proporciona, se utiliza la etiqueta predeterminada del proyecto.
page entero No 1 El número de página para la paginación (utilizado como cursor). Debe ser mayor que 0.
q cadena No La consulta de búsqueda para filtrar las cadenas de traducción por su texto de origen.

Respuestas

Respuesta de éxito

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 respuesta
Campo Tipo Descripción
total_strings_count entero El número total de cadenas traducibles en el archivo de origen.
translation_strings array[objeto] El array de objetos de cadenas de traducción (paginado, máximo 500 por página).
translation_strings[].source cadena El texto de origen original que se va a traducir.
translation_strings[].translations objeto Un hash de traducciones donde las claves son códigos ISO de idiomas y los valores son el texto traducido.
cursor entero El cursor de página actual utilizado para la paginación.

Respuestas de error

Archivo de origen no encontrado
404 Not Found
{
  "error": "Source file not found"
}
No autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Prohibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parámetros no válidos
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Peticiones de ejemplo

Petición 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"

Una petición con etiqueta de archivo:

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"

Una petición con paginación y búsqueda:

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"

Ejemplos 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"

Crear el archivo de origen

Registra un nuevo archivo de origen en su proyecto para que esté listo para traducir.

Este endpoint crea la entrada del archivo y establece su configuración de traducción, pero no adjunta el contenido real del archivo.

Después de crear el archivo, deberá utilizar el endpoint Procesar el archivo de origen para subir el contenido e iniciar el proceso de traducción.

Petición HTTP

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

Parámetros

Parámetro Tipo Obligatorio Descripción
file_path cadena La ruta donde debe almacenarse el archivo de origen en el proyecto. Debe tener una extensión compatible.
output_file_path cadena El patrón de ruta de salida para los archivos traducidos. Utilice {{lang}} como marcador de posición para el código de idioma.
translations array[objeto] No Los archivos de traducción preexistentes que se subirán junto con el archivo de origen. Estos archivos se almacenarán tal como se proporcionan, y sus cadenas no serán retraducidas por PTC. Tenga en cuenta que no se recomienda proporcionar traducciones existentes, ya que PTC produce mejores resultados cuando puede utilizar el contexto completo de su proyecto y traducir desde cero.
translations[].target_language_iso cadena El código ISO del idioma de destino para esta traducción. Puede encontrar la lista completa de idiomas compatibles y sus códigos ISO en el endpoint Listar todos los idiomas de destino.
translations[].file archivo El archivo de traducción que se va a subir.
additional_translation_files array[objeto] No Configuraciones de archivos de salida adicionales para formatos específicos. Para ver qué formatos admiten archivos de salida adicionales, consulte el endpoint Listar formatos de archivo compatibles. Para los formatos no compatibles, este campo se ignorará.
additional_translation_files[].type cadena Consulte los formatos de archivo compatibles para obtener más detalles.
additional_translation_files[].path cadena El patrón de ruta para el archivo.

Respuestas

Respuesta de éxito

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 respuesta
Campo Tipo Descripción
source_file.id entero El identificador único del archivo de origen creado.
source_file.file_path cadena La ruta del archivo de origen dentro del proyecto.
source_file.created_at cadena Una marca de tiempo ISO 8601 que indica cuándo se creó originalmente el archivo de origen.
source_file.file_tag.id entero El identificador de la etiqueta de archivo.
source_file.file_tag.name cadena El nombre de la etiqueta de archivo.

Respuestas de error

Fallo de validación
422 Unprocessable Entity
{
  "success": false,
  "error": "Source file creation failed"
}
No autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Prohibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Peticiones de ejemplo

Creación básica de archivo de origen:

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"

Petición con 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"

Petición con traducciones preexistentes:

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"

Petición con archivos de salida adicionales:

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"

Ejemplos de código

  • JavaScript (FormData)
  • Python (requests)
  • PHP (cURL)
  • Node.js (axios)
  • Cuerpo de la petición 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"
}

Procesar el archivo de origen

Sube contenido a un archivo de origen existente e inicia el proceso de traducción.

Este endpoint reemplaza el contenido actual del archivo, actualiza las cadenas traducibles almacenadas e inicia la traducción automática.

Para utilizar este endpoint, el archivo de origen ya debe existir en el proyecto. Si aún no lo ha creado, consulte Crear el archivo de origen.

Petición HTTP

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

Parámetros

Parámetro Tipo Obligatorio Descripción
file archivo El archivo de origen que se va a subir. El contenido del archivo se valida para garantizar que coincida con su extensión declarada. Por ejemplo, si la extensión del archivo es .json, el contenido subido debe ser un archivo JSON válido.
file_path cadena La ruta al archivo de origen existente en el proyecto que debe actualizarse.
file_tag_name cadena No El nombre de la etiqueta de archivo asociada al archivo de origen. Si no se proporciona, se utiliza la etiqueta de archivo predeterminada del proyecto.
callback_url cadena No La URL que recibe notificaciones de webhook cuando se completa el procesamiento del archivo.

Respuestas

Respuesta de éxito

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 respuesta
Campo Tipo Descripción
source_file.id entero El identificador único del archivo de origen procesado.
source_file.file_path cadena La ruta del archivo de origen dentro del proyecto.
source_file.created_at cadena Una marca de tiempo ISO 8601 que indica cuándo se creó originalmente el archivo de origen.
source_file.file_tag.id entero El identificador de la etiqueta de archivo.
source_file.file_tag.name cadena El nombre de la etiqueta de archivo.

Respuestas de error

Archivo de origen no encontrado
422 Unprocessable Entity
{
  "errors": {
    "file": ["File format is invalid or not supported"]
  }
}
No autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Prohibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Flujo de trabajo

  1. Requisito previo: El archivo de origen ya debe estar creado mediante Crear el archivo de origen.
  2. Subida del archivo: Se sube el contenido nuevo y se reemplaza el contenido existente del archivo.
  3. Procesamiento: Las nuevas cadenas traducibles se extraen y se traducen automáticamente.
  4. Callback: Se envía una notificación de webhook opcional cuando finaliza el procesamiento.

Callback de webhook

Cuando se proporciona una callback_url, PTC enviará una petición POST a esa URL cuando se complete el procesamiento.

Cuerpo de la petición 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"
}

Peticiones de ejemplo

Procesamiento básico de archivo:

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"

Petición con 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"

Ejemplos 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 archivo compatibles

El endpoint admite varios formatos de archivo traducibles, como JSON, PO/POT, XLIFF y archivos Properties, entre otros. La validación del formato de archivo se produce durante la subida para garantizar la compatibilidad.

Utilice el endpoint Listar formatos de archivo compatibles para obtener la lista completa de formatos compatibles.


Obtener el estado de la traducción

Recupera el progreso de traducción actual para un archivo de origen específico, incluyendo cuánto se ha completado y su estado de procesamiento general.

Esto es útil para:

  • Monitorización del progreso: hacer un seguimiento del progreso de la traducción en trabajos de larga duración
  • Actualizaciones de la interfaz de usuario: mostrar porcentajes de finalización en su aplicación
  • Integración del flujo de trabajo: desencadenar acciones cuando la traducción alcanza un umbral definido

Petición HTTP

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

Parámetros

Parámetro Tipo Obligatorio Descripción
file_path cadena La ruta del archivo de origen dentro del proyecto.
file_tag_name cadena No El nombre de la etiqueta de archivo. Si no se proporciona, se utiliza la etiqueta de archivo predeterminada del proyecto.

Respuestas

Respuesta de éxito

200 OKapplication/json
{
  "translation_status": {
    "status": "completed",
    "completeness": 100
  }
}
Esquema de respuesta
Campo Tipo Descripción
translation_status.status cadena El estado de procesamiento actual del archivo de origen. Vea los valores de estado a continuación.
translation_status.completeness número El porcentaje de cadenas traducidas (0–100). Se calcula como (completed_translatable_strings / total_translatable_strings) × 100.

Valores de estado

El campo status puede contener los siguientes valores:

Estado Descripción
pending El archivo de origen está a la espera de ser procesado.
processing La traducción está actualmente en curso.
completed Se han completado todas las traducciones.
failed El proceso de traducción se ha encontrado con errores.

Respuestas de error

Archivo de origen no encontrado
404 Not Found
{
  "error": "Source file not found"
}
No autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Prohibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parámetros no válidos
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Peticiones de ejemplo

Petición 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"

Petición con etiqueta de archivo:

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"

Ejemplos 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"

Descargar todas las traducciones

Descarga todos los archivos traducidos para un archivo de origen específico como un archivo comprimido ZIP.

Este endpoint crea y devuelve un archivo comprimido que contiene todos los archivos de traducción en los idiomas de destino para el archivo de origen especificado.

Si no hay traducciones disponibles para el archivo, la petición devolverá un error 404 No encontrado.

Petición HTTP

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

Parámetros

Parámetro Tipo Obligatorio Descripción
file_path cadena La ruta del archivo de origen dentro del proyecto.
file_tag_name cadena No El nombre de la etiqueta de archivo. Si no se proporciona, se utiliza la etiqueta de archivo predeterminada del proyecto. Un archivo de origen se identifica de forma exclusiva mediante la combinación de file_path y file_tag_name.

Respuestas

Respuesta de éxito

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

PTC procesa las traducciones de forma asíncrona. Por lo general, hay una breve espera entre la subida de un archivo de origen y la disponibilidad de las traducciones para descargar.

Cuando esto ocurra, espere el número de segundos especificado en Retry-After.

Respuestas de error

Archivo de origen no encontrado
404 Not Found
{
  "error": "Source file not found"
}
No hay traducciones disponibles
404 Not Found
{
  "error": "No translations are available for this source file"
}
No autorizado
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Prohibido
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parámetros no válidos
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Peticiones de ejemplo

Petición 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

Petición con etiqueta de archivo:

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

Ejemplos 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"}

Subir archivos de origen por lotes

Sube un archivo comprimido ZIP que contiene múltiples archivos traducibles. Cada archivo del archivo comprimido se extrae, se valida y se procesa. Los formatos compatibles se identifican automáticamente.

Esta es la versión por lotes de Procesar el archivo de origen, diseñada para acelerar las actualizaciones a gran escala.

Información adicional

  • Si un archivo coincide con un archivo de origen existente, se actualiza con el nuevo contenido y las traducciones se desencadenan de nuevo.
  • Si un archivo es compatible pero no coincide con ningún archivo de origen existente, se añade a la lista not_found_files y se ignora.
  • Los archivos con formatos no compatibles se enumeran en unsupported_files y se ignoran.
  • Los archivos con contenido no válido también se enumeran en unsupported_files y se ignoran.
  • Los archivos comprimidos grandes pueden tardar más en procesarse. Los archivos se procesan uno a uno para gestionar los recursos, por lo que es mejor dividir las subidas muy grandes (más de 100 archivos) en lotes más pequeños. Todos los archivos del archivo comprimido se configuran para traducirse automáticamente.
  • El archivo ZIP subido debe ser válido y legible. Todos los archivos que contiene deben estar en un formato compatible. Los nombres de archivo no deben incluir caracteres especiales que puedan causar problemas de ruta.
  • Si se proporciona una callback_url, se envía una petición POST para cada archivo de origen procesado con sus resultados.

Petición HTTP

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

Parámetros

Parámetro Tipo Obligatorio Descripción
zip_file archivo Un archivo comprimido ZIP que contiene los archivos de origen que se van a subir. Debe ser un archivo ZIP válido.
file_tag_name cadena No El nombre de la etiqueta de archivo que se asociará a todos los archivos de origen del archivo comprimido. Si no se especifica, se utiliza la etiqueta de archivo predeterminada del proyecto. Cada archivo de origen se identifica de forma exclusiva mediante la combinación de file_path y file_tag_name.
callback_url cadena No La URL que recibe notificaciones de webhook cuando se procesa cada archivo.

Estructura esperada del archivo ZIP

El archivo ZIP puede contener archivos de origen en cualquier estructura de directorios. La estructura de directorios se conserva y los archivos se procesan de forma recursiva.

Estructura ZIP de ejemplo:

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 archivo compatibles:

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

Respuestas

Respuesta de éxito

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 respuesta
Campo Tipo Descripción
success booleano Si la operación de subida por lotes se realizó correctamente.
file_tag objeto La información de la etiqueta de archivo.
file_tag.id entero El identificador de la etiqueta de archivo.
file_tag.name cadena El nombre de la etiqueta de archivo.
processed_files array[objeto] Un array de archivos de origen que se procesaron correctamente.
processed_files[].id entero El identificador único del archivo de origen creado.
processed_files[].file_path cadena La ruta del archivo de origen, conservando la estructura ZIP original.
processed_files[].created_at cadena Una marca de tiempo ISO 8601 que indica cuándo se creó el archivo de origen.
processed_files[].file_tag objeto La información de la etiqueta de archivo.
processed_files[].file_tag.id entero El identificador de la etiqueta de archivo.
processed_files[].file_tag.name cadena El nombre de la etiqueta de archivo.
unsupported_files array[cadena] Un array de nombres de archivo que no tienen un formato compatible.
not_found_files array[cadena] Un array de archivos compatibles que no coincidieron con ningún archivo de origen existente y fueron ignorados.

Respuestas de error

Archivo ZIP no válido

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

Fallo de procesamiento

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

No autorizado

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

Prohibido

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

Callback de webhook

Cuando se proporciona una callback_url, se envía una petición POST por cada archivo procesado.

Cuerpo de la petición de callback (por archivo):

{
  "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"
}

Peticiones de ejemplo

Subida básica por lotes:

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"

Petición con 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"

Ejemplos 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"
Siguiente:

Buscar formatos de archivo compatibles e idiomas de destino a través de la API →