Carica e gestisci i file sorgente tramite l’API

API per caricare, sostituire, monitorare e scaricare traduzioni.

Che tu stia gestendo un singolo file o automatizzando un flusso di lavoro di localizzazione continuo, questa API ti offre il pieno controllo sui contenuti che invii per la traduzione e su come ricevi le traduzioni.

Come l’API PTC identifica e organizza i file sorgente

L’API PTC utilizza un sistema flessibile basato su tag di file e percorsi di file. Questi parametri lavorano insieme per garantire che ogni file che carichi, aggiorni o richiedi sia chiaramente definito e facile da gestire.

Tag di file

I tag di file sono un modo flessibile per raggruppare e organizzare i file sorgente nei progetti di traduzione. Puoi usarli come categorie per soddisfare le esigenze del tuo flusso di lavoro. Ad esempio, i tag di file possono mostrare:

  • Controllo della versione: v1.0, beta, production
  • Branch di funzionalità: user-auth, dashboard-redesign
  • Contesto dell’applicazione: mobile-app, admin-panel, marketing
  • Proprietà del team: frontend-team, content-team
  • Stato del flusso di lavoro: approved, pending-review, priority-high

I nomi dei tag di file sono facoltativi nella maggior parte delle operazioni API. Tuttavia, ogni file sorgente ha sempre almeno un tag. Un tag di file predefinito viene creato e assegnato automaticamente quando viene impostato un progetto. Questo comportamento predefinito mantiene i progetti organizzati anche in configurazioni semplici, consentendoti comunque di creare strutture di tag più avanzate quando necessario.

Nome del tag di file + percorso del file

Ogni file sorgente è identificato in modo univoco dalla combinazione del suo nome del tag di file e percorso del file.

  • Se non fornisci un tag di file personalizzato durante il caricamento o l’elaborazione di un file, verrà assegnato automaticamente il tag predefinito.
  • Il nome del tag + il percorso di un file definiscono insieme la sua identità. Questa combinazione garantisce che ogni file sia univoco all’interno del tuo progetto, anche se versioni o contesti diversi condividono lo stesso percorso del file.

Parametri di query

Quando si recupera un file specifico, gli endpoint correlati possono accettare parametri di query come:

  • file_tag_name – Il tag associato al file
  • file_path – Il percorso del file

Questi parametri ti consentono di individuare e recuperare con precisione i file corretti dal tuo progetto.


Elenca tutti i file sorgente nel progetto

Elenca tutti i file sorgente nel tuo progetto, con opzioni per filtrare, ordinare e impaginare i risultati. Questo è utile quando vuoi sfogliare i tuoi file, controllarne lo stato o trovare file specifici in base al tag, al percorso o al metodo di caricamento.

Richiesta HTTP

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

Parametri

ParametroTipoObbligatorioPredefinitoDescrizione
pageinteroNo1Il numero di pagina per l’impaginazione. Deve essere maggiore di 0.
per_pageinteroNo50Il numero di elementi per pagina. Deve essere maggiore di 0.
order_bystringaNocreated_atIl campo in base al quale ordinare. Valori consentiti: id, created_at, updated_at.
sortstringaNodescLa direzione dell’ordinamento. Valori consentiti: asc, desc.
file_pathstringaNoFiltra per percorso del file esatto.
upload_originstringaNoFiltra in base a come è stato caricato il file. I valori consentiti includono: git, manual, api.

Risposte

Risposta di successo

  • Codice: 200 OK
  • Tipo di contenuto: 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
  }
}
Schema di risposta

Oggetto file sorgente:

CampoTipoDescrizione
idinteroL’identificatore univoco per il file sorgente.
file_pathstringaIl percorso del file di origine all’interno del progetto.
translation_pathstringaIl modello per dove salvare i file tradotti.
additional_translation_filesarray[string]I percorsi per eventuali file di output aggiuntivi.
statusstringaLo stato di elaborazione corrente del file sorgente.
upload_originstringaCome è stato caricato il file (git, manual, api).
created_atstringaUn timestamp ISO 8601 che indica quando è stato creato originariamente il file di origine.
updated_atstringaUn timestamp ISO 8601 che indica quando il file sorgente è stato aggiornato l’ultima volta.
file_tagobjectInformazioni sul tag di file.
file_tag.idinteroL’identificatore del tag file.
file_tag.namestringaIl nome del tag file.
download_urlstringaL’URL per scaricare le traduzioni per questo file sorgente.

Oggetto impaginazione:

CampoTipoDescrizione
pageinteroIl numero di pagina corrente.
per_pageinteroIl numero di elementi per pagina.
totalinteroIl numero totale di file sorgente.
total_pagesinteroIl numero totale di pagine.
has_next_pagebooleanSe è disponibile una pagina successiva.
has_previous_pagebooleanSe è disponibile una pagina precedente.

Risposte di errore

Non autorizzato
  • Codice: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibito
  • Codice: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parametri non validi
  • Codice: 422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Esempi di richieste

Richiesta di base:

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

Richiesta filtrata:

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"

Esempi di codice

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);

Ottieni le stringhe di traduzione

Recupera tutte le stringhe traducibili da un file sorgente specifico, insieme alle loro traduzioni esistenti in tutte le lingue di destinazione.

Questo endpoint è utile per recuperare contenuti che devono essere tradotti o che sono già stati tradotti. Il file sorgente è identificato da file_path e file_tag_name.

Richiesta HTTP

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

Parametri

ParametroTipoObbligatorioPredefinitoDescrizione
file_pathstringaIl percorso del file di origine all’interno del progetto.
file_tag_namestringaNoIl nome del tag di file. Se non fornito, viene utilizzato il tag predefinito del progetto.
pageinteroNo1Il numero di pagina per l’impaginazione (utilizzato come cursore). Deve essere maggiore di 0.
qstringaNoLa query di ricerca per filtrare le stringhe di traduzione in base al loro testo sorgente.

Risposte

Risposta di successo

  • Codice: 200 OK
  • Tipo di contenuto: 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
}
Schema di risposta
CampoTipoDescrizione
total_strings_countinteroIl numero totale di stringhe traducibili nel file sorgente.
translation_stringsarray[object]L’array di oggetti stringa di traduzione (impaginato, massimo 500 per pagina).
translation_strings[].sourcestringaIl testo sorgente originale da tradurre.
translation_strings[].translationsobjectUn hash di traduzioni in cui le chiavi sono i codici ISO della lingua e i valori sono il testo tradotto.
cursorinteroIl cursore della pagina corrente utilizzato per l’impaginazione.

Risposte di errore

File di origine non trovato
  • Codice: 404 Not Found
{
  "error": "Source file not found"
}
Non autorizzato
  • Codice: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibito
  • Codice: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parametri non validi
  • Codice: 422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Esempi di richieste

Richiesta di base:

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 richiesta con tag di file:

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 richiesta con impaginazione e ricerca:

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"

Esempi di codice

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);


Crea il file sorgente

Registra un nuovo file sorgente nel tuo progetto in modo che sia pronto per la traduzione.

Questo endpoint crea la voce del file e ne imposta la configurazione di traduzione, ma non allega il contenuto effettivo del file.

Dopo aver creato il file, dovrai usare l’endpoint Process the Source File per caricare il contenuto e avviare il processo di traduzione.

Richiesta HTTP

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

Parametri

ParametroTipoObbligatorioDescrizione
file_pathstringaIl percorso in cui il file sorgente deve essere archiviato nel progetto. Deve avere un estensione supportata.
output_file_pathstringaIl modello di percorso di output per i file tradotti. Usa {{lang}} come placeholder per il codice della lingua.
translationsarray[object]NoI file di traduzione preesistenti da caricare insieme al file sorgente. Questi file verranno archiviati come forniti e le loro stringhe non verranno ritradotte da PTC.
Tieni presente che fornire traduzioni esistenti non è raccomandato, poiché PTC produce risultati migliori quando può utilizzare il contesto completo del tuo progetto e tradurre da zero.
translations[].target_language_isostringaIl codice ISO della lingua di destinazione per questa traduzione. Puoi trovare l’elenco completo delle lingue supportate e i loro codici ISO nell’endpoint Elenca tutte le lingue di destinazione.
translations[].filefileIl file di traduzione da caricare.
additional_translation_filesarray[object]NoConfigurazioni di file di output aggiuntive per formati specifici.
Per vedere quali formati supportano file di output aggiuntivi, fai riferimento all’endpoint Elenca i formati di file supportati. Per i formati non supportati, questo campo verrà ignorato.
additional_translation_files[].typestringaVedi formati di file supportati per maggiori dettagli.
additional_translation_files[].pathstringaIl modello di percorso per il file.

Risposte

Risposta di successo

  • Codice: 201 Created
  • Tipo di contenuto: 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"
    }
  }
}
Schema di risposta
CampoTipoDescrizione
source_file.idinteroL’identificatore univoco per il file di origine creato.
source_file.file_pathstringaIl percorso del file di origine all’interno del progetto.
source_file.created_atstringaUn timestamp ISO 8601 che indica quando è stato creato originariamente il file di origine.
source_file.file_tag.idinteroL’identificatore del tag file.
source_file.file_tag.namestringaIl nome del tag file.

Risposte di errore

Validazione non riuscita
  • Codice: 422 Unprocessable Entity
{
  "success": false,
  "error": "Source file creation failed"
}
Non autorizzato
  • Codice: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibito
  • Codice: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Esempi di richieste

Creazione di file sorgente di base:

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"

Richiesta con URL di callback:

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"

Richiesta con traduzioni preesistenti:

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"

Richiesta con file di output aggiuntivi:

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"

Esempi di codice

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

Elabora il file di origine

Carica il contenuto in un file di origine esistente e avvia il processo di traduzione.

Questo endpoint sostituisce il contenuto attuale del file, aggiorna le stringhe traducibili memorizzate e avvia la traduzione automatica.

Per utilizzare questo endpoint, il file di origine deve già esistere nel progetto. Se non l’hai ancora creato, consulta Crea il file di origine.

Richiesta HTTP

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

Parametri

ParametroTipoObbligatorioDescrizione
filefileIl file di origine da caricare. Il contenuto del file viene convalidato per garantire che corrisponda all’estensione dichiarata. Ad esempio, se l’estensione del file è .json, il contenuto caricato deve essere un JSON valido.
file_pathstringaIl percorso del file di origine esistente nel progetto che deve essere aggiornato.
file_tag_namestringaNoIl nome del tag di file associato al file di origine. Se non viene fornito, viene utilizzato il tag di file predefinito del progetto.
callback_urlstringaNoL’URL che riceve le notifiche webhook al termine dell’elaborazione del file.

Risposte

Risposta di successo

  • Codice: 200 OK
  • Tipo di contenuto: 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"
    }
  }
}
Schema di risposta
CampoTipoDescrizione
source_file.idinteroL’identificatore univoco per il file di origine elaborato.
source_file.file_pathstringaIl percorso del file di origine all’interno del progetto.
source_file.created_atstringaUn timestamp ISO 8601 che indica quando è stato creato originariamente il file di origine.
source_file.file_tag.idinteroL’identificatore del tag file.
source_file.file_tag.namestringaIl nome del tag file.

Risposte di errore

File di origine non trovato
  • Codice: 422 Unprocessable Entity
{
  "errors": {
    "file": ["File format is invalid or not supported"]
  }
}
Non autorizzato
  • Codice: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibito
  • Codice: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Workflow

  1. Prerequisito: Il file di origine deve essere già stato creato tramite Crea il file di origine.
  2. Caricamento file: Il nuovo contenuto viene caricato e sostituisce il contenuto del file esistente.
  3. Elaborazione: Le nuove stringhe traducibili vengono estratte e tradotte automaticamente.
  4. Callback: Viene inviata una notifica webhook facoltativa al termine dell’elaborazione.

Webhook callback

Quando viene fornito un callback_url, PTC invierà una richiesta POST a tale URL al termine dell’elaborazione.

Corpo della richiesta di 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"
}

Esempi di richieste

Elaborazione di base del file:

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"

Richiesta con URL di 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"

Esempi di codice

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);

Formati di file supportati

L’endpoint supporta vari formati di file traducibili, inclusi JSON, PO/POT, XLIFF e file Properties, tra gli altri.
La convalida del formato del file avviene durante il caricamento per garantire la compatibilità.

Usa l’endpoint List Supported File Formats per ottenere l’elenco completo dei formati supportati.


Ottieni lo stato della traduzione

Recupera l’avanzamento della traduzione corrente per un file sorgente specifico, inclusa la quantità completata e lo stato generale di elaborazione.

Questo è utile per:

  • Monitoraggio dell’avanzamento – Monitoraggio dell’avanzamento della traduzione per lavori di lunga durata
  • Aggiornamenti dell’interfaccia utente – Visualizzazione delle percentuali di completamento nella tua applicazione
  • Integrazione del flusso di lavoro – Attivazione di azioni quando la traduzione raggiunge una soglia definita

Richiesta HTTP

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

Parametri

ParametroTipoObbligatorioDescrizione
file_pathstringaIl percorso del file di origine all’interno del progetto.
file_tag_namestringaNoIl nome del tag file. Se non specificato, viene utilizzato il tag file predefinito del progetto.

Risposte

Risposta di successo

  • Codice: 200 OK
  • Tipo di contenuto: application/json
{
  "translation_status": {
    "status": "completed",
    "completeness": 100
  }
}
Schema di risposta
CampoTipoDescrizione
translation_status.statusstringaLo stato di elaborazione attuale del file di origine. Vedi i valori di stato di seguito.
translation_status.completenessnumeroLa percentuale di stringhe tradotte (0–100). Calcolata come (completed_translatable_strings / total_translatable_strings) × 100.

Valori di stato

Il campo status può contenere i seguenti valori:

StatoDescrizione
pendingIl file di origine è in attesa di essere elaborato.
processingLa traduzione è attualmente in corso.
completedTutte le traduzioni sono state completate.
failedIl processo di traduzione ha riscontrato errori.

Risposte di errore

File di origine non trovato
  • Codice: 404 Not Found
{
  "error": "Source file not found"
}
Non autorizzato
  • Codice: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibito
  • Codice: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parametri non validi
  • Codice: 422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Esempi di richieste

Richiesta di base:

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

Richiesta con tag di file:

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"

Esempi di codice

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`);


Scarica tutte le traduzioni

Scarica tutti i file tradotti per un file sorgente specifico come archivio ZIP.

Questo endpoint crea e restituisce un archivio compresso contenente tutti i file di traduzione nelle lingue di destinazione per il file sorgente specificato.

Se non sono disponibili traduzioni per il file, la richiesta restituirà un errore 404 Not Found.

Richiesta HTTP

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

Parametri

ParametroTipoObbligatorioDescrizione
file_pathstringaIl percorso del file di origine all’interno del progetto.
file_tag_namestringaNoIl nome del tag di file. Se non viene fornito, viene utilizzato il tag di file predefinito del progetto. Un file di origine è identificato in modo univoco dalla combinazione di file_path e file_tag_name.

Risposte

Risposta di successo

  • Codice: 200 OK
  • Tipo di contenuto: application/zip
  • Corpo della risposta: File ZIP binario contenente i file di traduzione
  • Intestazioni:
    • Content-Type: application/zip
    • Content-Disposition: attachment; filename="translations-{source_file_id}.zip"
Contenuto dell’archivio ZIP

Il file ZIP scaricato contiene:

  • File di traduzione – Uno per lingua di destinazione per il file di origine specificato
  • File di traduzione aggiuntivi – File generati aggiuntivi (se configurati), posizionati a livello di root seguendo i percorsi configurati
  • Struttura dei file – Corrisponde alla configurazione impostata durante la creazione del file di origine

Esempio di struttura 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

Risposta di stato

Traduzioni in corso
  • Codice: 202 Accepted
  • Intestazione: Retry-After: 30
{
  "status": "processing",
  "message": "Translations are still in progress. Please retry after the specified delay.",
  "retry_after": 30
}

PTC elabora le traduzioni in modo asincrono. Solitamente c’è una breve attesa tra il caricamento di un file sorgente e la disponibilità delle traduzioni per il download.

Quando succede, attendi il numero di secondi specificato in Retry-After.

Risposte di errore

File di origine non trovato
  • Codice: 404 Not Found
{
  "error": "Source file not found"
}
Nessuna traduzione disponibile
  • Codice: 404 Not Found
{
  "error": "No translations are available for this source file"
}
Non autorizzato
  • Codice: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Proibito
  • Codice: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Parametri non validi
  • Codice: 422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Esempi di richieste

Richiesta di base:

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

Richiesta con tag di file:

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

Esempi di codice

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');

Carica file di origine in blocco

Carica un archivio ZIP contenente più file traducibili. Ogni file nell’archivio viene estratto, convalidato ed elaborato. I formati supportati vengono identificati automaticamente.

Questa è la versione batch di Elabora file di origine, progettata per velocizzare gli aggiornamenti su larga scala.

Informazioni aggiuntive

  • Se un file corrisponde a un file di origine esistente, viene aggiornato con il nuovo contenuto e le traduzioni vengono attivate di nuovo.
  • Se un file è supportato ma non corrisponde ad alcun file di origine esistente, viene aggiunto all’elenco not_found_files e ignorato.
  • I file con formati non supportati sono elencati in unsupported_files e ignorati.
  • Anche i file con contenuto non valido sono elencati in unsupported_files e ignorati.
  • Gli archivi di grandi dimensioni potrebbero richiedere più tempo per l’elaborazione. I file vengono elaborati uno per uno per gestire le risorse, quindi è meglio dividere i caricamenti molto grandi (più di 100 file) in batch più piccoli. Tutti i file nell’archivio sono impostati per la traduzione automatica.
  • Lo ZIP caricato deve essere valido e leggibile. Tutti i file all’interno devono essere in un formato supportato. I nomi dei file non devono includere caratteri speciali che potrebbero causare problemi di percorso.
  • Se viene fornito un callback_url, viene inviata una richiesta POST per ogni file di origine elaborato con i relativi risultati.

Richiesta HTTP

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

Parametri

ParametroTipoObbligatorioDescrizione
zip_filefileUn archivio ZIP contenente i file di origine da caricare. Deve essere un file ZIP valido.
file_tag_namestringaNoIl nome del tag file da associare a tutti i file di origine nell’archivio. Se non specificato, viene utilizzato il tag file predefinito del progetto. Ogni file di origine è identificato in modo univoco dalla combinazione di file_path e file_tag_name.
callback_urlstringaNoL’URL che riceve le notifiche webhook quando ogni file viene elaborato.

Struttura prevista del file ZIP

Il file ZIP può contenere file di origine in qualsiasi struttura di directory. La struttura di directory viene conservata e i file vengono elaborati in modo ricorsivo.

Esempio di struttura 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)

Tipi di file supportati:

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

Risposte

Risposta di successo

  • Codice: 200 OK
  • Tipo di contenuto: 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"]
}
Schema di risposta
CampoTipoDescrizione
successbooleanIndica se l’operazione di caricamento in blocco è andata a buon fine.
file_tagobjectLe informazioni del tag file.
file_tag.idinteroL’identificatore del tag file.
file_tag.namestringaIl nome del tag file.
processed_filesarray[object]Un array di file di origine che sono stati elaborati correttamente.
processed_files[].idinteroL’identificatore univoco per il file di origine creato.
processed_files[].file_pathstringaIl percorso del file di origine, preservando la struttura ZIP originale.
processed_files[].created_atstringaUn timestamp ISO 8601 che indica quando è stato creato il file di origine.
processed_files[].file_tagobjectLe informazioni del tag file.
processed_files[].file_tag.idinteroL’identificatore del tag file.
processed_files[].file_tag.namestringaIl nome del tag file.
unsupported_filesarray[string]Un array di nomi di file che non sono in un formato supportato.
not_found_filesarray[string]Un array di file supportati che non corrispondevano ad alcun file di origine esistente e sono stati ignorati.

Risposte di errore

File ZIP non valido

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

Elaborazione non riuscita

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

Non autorizzato

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

Proibito

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

Webhook callback

Quando viene fornito un callback_url, viene inviata una richiesta POST per ogni file elaborato.

Corpo della richiesta di callback (per file):

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

Esempi di richieste

Caricamento in blocco di base:

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"

Richiesta con URL di callback:

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"

Esempi di codice

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`);
Scorri verso l'alto