Cargue y gestione los archivos de origen a través de la API

API para subir archivos, reemplazar obsoletos, seguir progreso y descargar.

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

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

La API de PTC utiliza un sistema flexible basado en etiquetas de archivo y rutas de archivo. Estos parámetros funcionan conjuntamente para garantizar que cada archivo que cargue, 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 proyectos de traducción. Puede utilizarlas como categorías para que coincidan con las necesidades de su flujo de trabajo. Por ejemplo, las etiquetas de archivo pueden mostrar:

  • Control de versiones: v1.0, beta, production
  • Ramas de funciones: 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. Una etiqueta de archivo predeterminada se crea y se asigna automáticamente cuando se configura 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 por la combinación de su nombre de etiqueta de archivo y su ruta de archivo.

  • Si no proporciona una etiqueta de archivo personalizada al cargar o procesar un archivo, se asignará automáticamente la etiqueta predeterminada.
  • El nombre de la etiqueta + la ruta de un archivo definen conjuntamente 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 al archivo

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


Listar todos los archivos de origen del proyecto

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

Solicitud HTTP

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

Parámetros

ParámetroTipoObligatorioPredeterminadoDescripción
pageenteroNo1El número de página para la paginación. Debe ser mayor que 0.
per_pageenteroNo50El número de elementos por página. Debe ser mayor que 0.
order_bycadenaNocreated_atEl campo por el que ordenar. Valores permitidos: id, created_at, updated_at.
sortcadenaNodescLa dirección de la ordenación. Valores permitidos: asc, desc.
file_pathcadenaNoFiltra por ruta de archivo exacta.
upload_origincadenaNoFiltra por cómo se cargó el archivo. Los valores permitidos incluyen: git, manual, api.

Respuestas

Respuesta correcta

  • Código: 200 OK
  • Tipo de contenido: application/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=locale/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 de archivo de origen:

CampoTipoDescripción
identeroEl identificador único del archivo de origen.
file_pathcadenaLa ruta al archivo de origen dentro del proyecto.
translation_pathcadenaEl patrón para dónde deben guardarse los archivos traducidos.
additional_translation_filesarray[string]Las rutas para cualquier archivo de salida adicional.
statuscadenaEl estado de procesamiento actual del archivo de origen.
upload_origincadenaCómo se cargó el archivo (git, manual, api).
created_atcadenaUna marca de tiempo ISO 8601 que indica cuándo se creó originalmente el archivo de origen.
updated_atcadenaUna marca de tiempo ISO 8601 que indica cuándo se actualizó por última vez el archivo de origen.
file_tagobjectInformación sobre la etiqueta de archivo.
file_tag.identeroEl identificador de la etiqueta de archivo.
file_tag.namecadenaEl nombre de la etiqueta de archivo.
download_urlcadenaLa URL para descargar las traducciones de este archivo de origen.

Objeto de paginación:

CampoTipoDescripción
pageenteroEl número de página actual.
per_pageenteroEl número de elementos por página.
totalenteroEl número total de archivos de origen.
total_pagesenteroEl número total de páginas.
has_next_pagebooleanoSi hay una página siguiente disponible.
has_previous_pagebooleanoSi hay una página anterior disponible.

Respuestas de error

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

Ejemplo de solicitudes

Solicitud básica:

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

Solicitud 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 "Content-Type: application/json"

Ejemplos de código

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);
import requests

headers = {
    'Content-Type': 'application/json'
}

params = {
    'file_tag_name': 'frontend',
    'page': 1,
    'per_page': 25
}

response = requests.get('https://app.ptc.wpml.org/api/v1/source_files', 
                       headers=headers, params=params)
data = response.json()
print(data)
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);
?>
const axios = require('axios');

const response = await axios.get('https://app.ptc.wpml.org/api/v1/source_files', {
  headers: {
    'Content-Type': 'application/json'
  },
  params: {
    file_tag_name: 'frontend',
    page: 1,
    per_page: 25
  }
});

console.log(response.data);

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.

Solicitud HTTP

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

Parámetros

ParámetroTipoObligatorioPredeterminadoDescripción
file_pathcadenaLa ruta al archivo de origen dentro del proyecto.
file_tag_namecadenaNoEl nombre de la etiqueta de archivo. Si no se proporciona, se utiliza la etiqueta predeterminada del proyecto.
pageenteroNo1El número de página para la paginación (utilizado como cursor). Debe ser mayor que 0.
qcadenaNoLa consulta de búsqueda para filtrar las cadenas de traducción por su texto de origen.

Respuestas

Respuesta correcta

  • Código: 200 OK
  • Tipo de contenido: application/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
CampoTipoDescripción
total_strings_countenteroEl número total de cadenas traducibles en el archivo de origen.
translation_stringsarray[object]La matriz de objetos de cadena de traducción (paginada, máximo 500 por página).
translation_strings[].sourcecadenaEl texto de origen original que se va a traducir.
translation_strings[].translationsobjectUn hash de traducciones donde las claves son códigos ISO de idioma y los valores son el texto traducido.
cursorenteroEl cursor de página actual utilizado para la paginación.

Respuestas de error

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

Ejemplo de solicitudes

Solicitud básica:

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

Una solicitud 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 "Content-Type: application/json"

Una solicitud 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 "Content-Type: application/json"

Ejemplos de código

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend&page=1&q=login', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

import requests

headers = {
    'Content-Type': 'application/json'
}

params = {
    'file_path': 'locales/en.po',
    'file_tag_name': 'frontend',
    'page': 1,
    'q': 'login'
}

response = requests.get('https://app.ptc.wpml.org/api/v1/source_files/translation_strings', 
                       headers=headers, params=params)
data = response.json()
print(data)
<?php
$params = http_build_query([
    'file_path' => 'locales/en.po',
    'file_tag_name' => 'frontend',
    'page' => 1,
    'q' => 'login'
]);

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?{$params}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);
?>

const axios = require('axios');

const response = await axios.get('https://app.ptc.wpml.org/api/v1/source_files/translation_strings', {
  headers: {
    'Content-Type': 'application/json'
  },
  params: {
    file_path: 'locales/en.po',
    file_tag_name: 'frontend',
    page: 1,
    q: 'login'
  }
});

console.log(response.data);


Crear el archivo de origen

Registra un nuevo archivo de origen en su proyecto para que esté listo para la traducción.

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

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

Solicitud HTTP

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

Parámetros

ParámetroTipoObligatorioDescripción
file_pathcadenaLa ruta donde se debe almacenar el archivo de origen en el proyecto. Debe tener una extensión admitida.
output_file_pathcadenaEl patrón de ruta de salida para los archivos traducidos. Utilice {{lang}} como un placeholder para el código de idioma.
translationsarray[object]NoLos archivos de traducción preexistentes para cargar junto con el archivo de origen. Estos archivos se almacenarán tal como se proporcionan, y sus cadenas no serán re-traducidas 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_isocadenaEl código ISO del idioma de destino para esta traducción. Puede encontrar la lista completa de idiomas admitidos y sus códigos ISO en el endpoint Listar todos los idiomas de destino.
translations[].filefileEl archivo de traducción para cargar.
additional_translation_filesarray[object]NoConfiguraciones 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 admitidos. Para los formatos no admitidos, este campo se ignorará.
additional_translation_files[].typecadenaConsulte los formatos de archivo admitidos para obtener más detalles.
additional_translation_files[].pathcadenaEl patrón de ruta para el archivo.

Respuestas

Respuesta correcta

  • Código: 201 Created
  • Tipo de contenido: application/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
CampoTipoDescripción
source_file.identeroEl identificador único para el archivo de origen creado.
source_file.file_pathcadenaLa ruta del archivo de origen dentro del proyecto.
source_file.created_atcadenaUna marca de tiempo ISO 8601 que indica cuándo se creó originalmente el archivo de origen.
source_file.file_tag.identeroEl identificador de la etiqueta de archivo.
source_file.file_tag.namecadenaEl nombre de la etiqueta de archivo.

Respuestas de error

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

Ejemplo de solicitudes

Creación básica de archivos de origen:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Content-Type: multipart/form-data" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{lang}.json" \
  -F "file_tag_name=frontend"

Solicitud con URL de retrollamada:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Content-Type: multipart/form-data" \
  -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"

Solicitud con traducciones preexistentes:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Content-Type: multipart/form-data" \
  -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"

Solicitud con archivos de salida adicionales:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Content-Type: multipart/form-data" \
  -F "file_path=src/messages.po" \
  -F "output_file_path=locales/{lang}/messages.po" \
  -F "additional_translation_files[mo]=locales/{lang}/messages.mo" \
  -F "additional_translation_files[json]=locales/{lang}/messages.json"

Ejemplos de código

const formData = new FormData();
formData.append('file_path', 'src/locales/en.json');
formData.append('output_file_path', 'src/locales/{lang}.json');
formData.append('file_tag_name', 'frontend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files', {
  method: 'POST',
  body: formData
});

const data = await response.json();
console.log(data);


import requests

data = {
    'file_path': 'src/locales/en.json',
    'output_file_path': 'src/locales/{lang}.json',
    'file_tag_name': 'frontend',
    'callback_url': 'https://your-app.com/webhooks/complete'
}

response = requests.post('https://app.ptc.wpml.org/api/v1/source_files', data=data)
result = response.json()
print(result)

<?php
$data = [
    'file_path' => 'src/locales/en.json',
    'output_file_path' => 'src/locales/{lang}.json',
    'file_tag_name' => 'frontend',
    'callback_url' => 'https://your-app.com/webhooks/complete'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/source_files',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
print_r($result);
?>

const axios = require('axios');
const FormData = require('form-data');

const formData = new FormData();
formData.append('file_path', 'src/locales/en.json');
formData.append('output_file_path', 'src/locales/{lang}.json');
formData.append('file_tag_name', 'frontend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await axios.post('https://app.ptc.wpml.org/api/v1/source_files', formData, {
  headers: formData.getHeaders()
});

console.log(response.data);


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

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

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

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

Solicitud HTTP

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

Parámetros

ParámetroTipoObligatorioDescripción
filefileEl archivo de origen que se va a cargar. 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 cargado debe ser JSON válido.
file_pathcadenaLa ruta al archivo de origen existente en el proyecto que se debe actualizar.
file_tag_namecadenaNoEl nombre de la etiqueta de archivo asociada con el archivo de origen. Si no se proporciona, se utiliza la etiqueta de archivo predeterminada del proyecto.
callback_urlcadenaNoLa URL que recibe notificaciones de webhook cuando se completa el procesamiento del archivo.

Respuestas

Respuesta correcta

  • Código: 200 OK
  • Tipo de contenido: application/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
CampoTipoDescripción
source_file.identeroEl identificador único para el archivo de origen procesado.
source_file.file_pathcadenaLa ruta del archivo de origen dentro del proyecto.
source_file.created_atcadenaUna marca de tiempo ISO 8601 que indica cuándo se creó originalmente el archivo de origen.
source_file.file_tag.identeroEl identificador de la etiqueta de archivo.
source_file.file_tag.namecadenaEl nombre de la etiqueta de archivo.

Respuestas de error

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

Flujo de trabajo

  1. Requisito previo: El archivo de origen ya debe haberse creado a través de Crear el archivo de origen.
  2. Carga de archivos: Se carga contenido nuevo y reemplaza el contenido del archivo existente.
  3. Procesamiento: Se extraen las nuevas cadenas traducibles 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 solicitud POST a esa URL cuando se complete el procesamiento.

Cuerpo de la solicitud 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"
}

Ejemplo de solicitudes

Procesamiento básico de archivos:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend"

Solicitud con URL de callback:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@messages.po" \
  -F "file_path=locales/messages.po" \
  -F "callback_url=https://your-app.com/webhooks/translation-complete"

Ejemplos de código

const formData = new FormData();
const fileInput = document.getElementById('file-input');
formData.append('file', fileInput.files[0]);
formData.append('file_path', 'src/locales/en.json');
formData.append('file_tag_name', 'frontend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/process', {
  method: 'POST',
  body: formData
});

const data = await response.json();
console.log(data);

import requests

files = {'file': open('updated_translations.json', 'rb')}
data = {
    'file_path': 'src/locales/en.json',
    'file_tag_name': 'frontend',
    'callback_url': 'https://your-app.com/webhooks/complete'
}

response = requests.post('https://app.ptc.wpml.org/api/v1/source_files/process', 
                        files=files, data=data)
result = response.json()
print(result)
<?php
$file_path = 'updated_translations.json';
$post_data = [
    'file' => new CURLFile($file_path),
    'file_path' => 'src/locales/en.json',
    'file_tag_name' => 'frontend',
    'callback_url' => 'https://your-app.com/webhooks/complete'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/source_files/process',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $post_data,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
print_r($result);
?>


const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const formData = new FormData();
formData.append('file', fs.createReadStream('updated_translations.json'));
formData.append('file_path', 'src/locales/en.json');
formData.append('file_tag_name', 'frontend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await axios.post('https://app.ptc.wpml.org/api/v1/source_files/process', formData, {
  headers: formData.getHeaders()
});

console.log(response.data);

Formatos de archivo admitidos

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

Utilice el punto de conexión Listar formatos de archivo admitidos para obtener la lista completa de formatos admitidos.


Obtener el estado de la traducción

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

Esto es útil para:

  • Supervisión del progreso: seguimiento del progreso de la traducción para trabajos de larga duración
  • Actualizaciones de la interfaz de usuario: visualización de porcentajes de finalización en su aplicación
  • Integración del flujo de trabajo: activación de acciones cuando la traducción alcanza un umbral definido

Solicitud HTTP

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

Parámetros

ParámetroTipoObligatorioDescripción
file_pathcadenaLa ruta al archivo de origen dentro del proyecto.
file_tag_namecadenaNoEl nombre de la etiqueta de archivo. Si no se proporciona, se utiliza la etiqueta de archivo predeterminada del proyecto.

Respuestas

Respuesta correcta

  • Código: 200 OK
  • Tipo de contenido: application/json
{
  "translation_status": {
    "status": "completed",
    "completeness": 100
  }
}
Esquema de respuesta
CampoTipoDescripción
translation_status.statuscadenaEl estado de procesamiento actual del archivo de origen. Consulte los valores de estado a continuación.
translation_status.completenessnúmeroEl porcentaje de cadenas traducidas (0–100). Calculado como (completed_translatable_strings / total_translatable_strings) × 100.

Valores de estado

El campo status puede contener los siguientes valores:

EstadoDescripción
pendingEl archivo de origen está esperando a ser procesado.
processingLa traducción está actualmente en curso.
completedSe han completado todas las traducciones.
failedEl proceso de traducción ha encontrado errores.

Respuestas de error

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

Ejemplo de solicitudes

Solicitud básica:

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

Solicitud 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 "Content-Type: application/json"

Ejemplos de código

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po&file_tag_name=frontend', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(`Translation ${data.translation_status.completeness}% complete`);

import requests

headers = {
    'Content-Type': 'application/json'
}

params = {
    'file_path': 'locales/en.po',
    'file_tag_name': 'frontend'
}

response = requests.get('https://app.ptc.wpml.org/api/v1/source_files/translation_status', 
                       headers=headers, params=params)
data = response.json()
print(f"Translation {data['translation_status']['completeness']}% complete")

<?php
$params = http_build_query([
    'file_path' => 'locales/en.po',
    'file_tag_name' => 'frontend'
]);

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/source_files/translation_status?{$params}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
echo "Translation " . $data['translation_status']['completeness'] . "% complete";
?>
const axios = require('axios');

const response = await axios.get('https://app.ptc.wpml.org/api/v1/source_files/translation_status', {
  headers: {
    'Content-Type': 'application/json'
  },
  params: {
    file_path: 'locales/en.po',
    file_tag_name: 'frontend'
  }
});

console.log(`Translation ${response.data.translation_status.completeness}% complete`);


Descargar todas las traducciones

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

Este punto de conexión 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 solicitud devolverá un error 404 No encontrado.

Solicitud HTTP

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

Parámetros

ParámetroTipoObligatorioDescripción
file_pathcadenaLa ruta al archivo de origen dentro del proyecto.
file_tag_namecadenaNoEl 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 única mediante la combinación de file_path y file_tag_name.

Respuestas

Respuesta correcta

  • Código: 200 OK
  • Tipo de contenido: application/zip
  • Cuerpo de la respuesta: Archivo ZIP binario que contiene archivos de traducción
  • Encabezados:
    • Content-Type: application/zip
    • Content-Disposition: attachment; filename="translations-{source_file_id}.zip"
Contenido del archivo ZIP

El archivo ZIP descargado contiene:

  • Archivos de traducción: uno por idioma de destino para el archivo de origen especificado
  • Archivos de traducción adicionales: archivos generados adicionales (si están configurados), colocados en el nivel raíz siguiendo sus rutas configuradas
  • Estructura de archivos: coincide con la configuración establecida durante la creación del archivo de origen

Ejemplo de estructura ZIP:

translations-123.zip
├── locales/es.json
├── locales/fr.json
├── locales/de.json
├── locales/es.po
├── locales/fr.po
├── locales/de.po
├── locales/es.mo
├── locales/fr.mo
├── locales/de.mo

Respuesta de estado

Traducciones en curso
  • Código: 202 Accepted
  • Encabezado: Retry-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. Normalmente hay una breve espera entre la carga de un archivo de origen y la disponibilidad de las traducciones para su descarga.

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

Respuestas de error

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

Ejemplo de solicitudes

Solicitud básica:

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

Solicitud 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 "Content-Type: application/json" \
  -o frontend-translations.zip

Ejemplos de código

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

if (response.ok) {
  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'translations.zip';
  document.body.appendChild(a);
  a.click();
  window.URL.revokeObjectURL(url);
}

import requests

headers = {
    'Content-Type': 'application/json'
}

params = {
    'file_path': 'locales/en.po',
    'file_tag_name': 'frontend'
}

response = requests.get('https://app.ptc.wpml.org/api/v1/source_files/download_translations', 
                       headers=headers, params=params)

if response.status_code == 200:
    with open('translations.zip', 'wb') as f:
        f.write(response.content)
    print("Translations downloaded successfully")
<?php
$params = http_build_query([
    'file_path' => 'locales/en.po',
    'file_tag_name' => 'frontend'
]);

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/source_files/download_translations?{$params}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode === 200) {
    file_put_contents('translations.zip', $response);
    echo "Translations downloaded successfully";
}
?>
const axios = require('axios');
const fs = require('fs');

const response = await axios.get('https://app.ptc.wpml.org/api/v1/source_files/download_translations', {
  headers: {
    'Content-Type': 'application/json'
  },
  params: {
    file_path: 'locales/en.po',
    file_tag_name: 'frontend'
  },
  responseType: 'stream'
});

response.data.pipe(fs.createWriteStream('translations.zip'));
console.log('Translations downloaded successfully');

Cargar archivos de origen de forma masiva

Carga un archivo ZIP que contiene varios archivos traducibles. Cada archivo en el archivo se extrae, se valida y se procesa. Los formatos admitidos se identifican automáticamente.

Esta es la versión por lotes de Procesar 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 activan de nuevo.
  • Si un archivo es compatible pero no coincide con ningún archivo de origen existente, se agrega a la lista not_found_files y se ignora.
  • Los archivos con formatos no admitidos 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 grandes pueden tardar más en procesarse. Los archivos se procesan uno por uno para administrar los recursos, por lo que es mejor dividir las cargas muy grandes (más de 100 archivos) en lotes más pequeños. Todos los archivos en el archivo se establecen para traducir automáticamente.
  • El ZIP cargado debe ser válido y legible. Todos los archivos dentro 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 solicitud POST para cada archivo de origen procesado con sus resultados.

Solicitud HTTP

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

Parámetros

ParámetroTipoObligatorioDescripción
zip_filefileUn archivo ZIP que contiene los archivos de origen para cargar. Debe ser un archivo ZIP válido.
file_tag_namecadenaNoEl nombre de la etiqueta de archivo que se asociará con todos los archivos de origen del archivo. 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_urlcadenaNoLa URL que recibe notificaciones de webhook cuando se procesa cada archivo.

Estructura de archivo ZIP esperada

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.

Ejemplo de estructura 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 archivo admitidos:

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

Respuestas

Respuesta correcta

  • Código: 200 OK
  • Tipo de contenido: application/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
CampoTipoDescripción
successbooleanoIndica si la operación de carga masiva se realizó correctamente.
file_tagobjectLa información de la etiqueta de archivo.
file_tag.identeroEl identificador de la etiqueta de archivo.
file_tag.namecadenaEl nombre de la etiqueta de archivo.
processed_filesarray[object]Una matriz de archivos de origen que se procesaron correctamente.
processed_files[].identeroEl identificador único para el archivo de origen creado.
processed_files[].file_pathcadenaLa ruta del archivo de origen, conservando la estructura ZIP original.
processed_files[].created_atcadenaUna marca de tiempo ISO 8601 que indica cuándo se creó el archivo de origen.
processed_files[].file_tagobjectLa información de la etiqueta de archivo.
processed_files[].file_tag.identeroEl identificador de la etiqueta de archivo.
processed_files[].file_tag.namecadenaEl nombre de la etiqueta de archivo.
unsupported_filesarray[string]Una matriz de nombres de archivo que no están en un formato admitido.
not_found_filesarray[string]Una matriz de archivos admitidos que no coincidieron con ningún archivo de origen existente y se ignoraron.

Respuestas de error

Archivo ZIP no válido

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

Error al procesar

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

No autorizado

  • Código: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}

Prohibido

  • Código: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Callback de webhook

Cuando se proporciona una callback_url, se envía una solicitud POST para cada archivo procesado.

Cuerpo de la solicitud de retrollamada (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": "locale/en.po"
}

Ejemplo de solicitudes

Carga masiva básica:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Content-Type: multipart/form-data" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend"

Solicitud con URL de retrollamada:

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

Ejemplos de código

const formData = new FormData();
const fileInput = document.getElementById('zip-file-input');
formData.append('zip_file', fileInput.files[0]);
formData.append('file_tag_name', 'backend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/bulk', {
  method: 'POST',
  body: formData
});

const data = await response.json();
console.log(`Processed ${data.processed_files.length} files`);
console.log(`Unsupported files: ${data.unsupported_files.join(', ')}`);

import requests

files = {'zip_file': open('source-files.zip', 'rb')}
data = {
    'file_tag_name': 'backend',
    'callback_url': 'https://your-app.com/webhooks/complete'
}

response = requests.post('https://app.ptc.wpml.org/api/v1/source_files/bulk', 
                        files=files, data=data)
result = response.json()

print(f"Processed {len(result['processed_files'])} files")
print(f"Unsupported files: {', '.join(result['unsupported_files'])}")

<?php
$zip_file_path = 'source-files.zip';
$post_data = [
    'zip_file' => new CURLFile($zip_file_path),
    'file_tag_name' => 'backend',
    'callback_url' => 'https://your-app.com/webhooks/complete'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/source_files/bulk',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $post_data,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
echo "Processed " . count($result['processed_files']) . " files";
?>
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const formData = new FormData();
formData.append('zip_file', fs.createReadStream('source-files.zip'));
formData.append('file_tag_name', 'backend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await axios.post('https://app.ptc.wpml.org/api/v1/source_files/bulk', formData, {
  headers: formData.getHeaders()
});

console.log(`Processed ${response.data.processed_files.length} files`);
Ir arriba