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.
Link rapidi API
Endpoint
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 filefile_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_filesParametri
| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
|---|---|---|---|---|
page | intero | No | 1 | Il numero di pagina per l’impaginazione. Deve essere maggiore di 0. |
per_page | intero | No | 50 | Il numero di elementi per pagina. Deve essere maggiore di 0. |
order_by | stringa | No | created_at | Il campo in base al quale ordinare. Valori consentiti: id, created_at, updated_at. |
sort | stringa | No | desc | La direzione dell’ordinamento. Valori consentiti: asc, desc. |
file_path | stringa | No | – | Filtra per percorso del file esatto. |
upload_origin | stringa | No | – | Filtra 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:
| Campo | Tipo | Descrizione |
|---|---|---|
id | intero | L’identificatore univoco per il file sorgente. |
file_path | stringa | Il percorso del file di origine all’interno del progetto. |
translation_path | stringa | Il modello per dove salvare i file tradotti. |
additional_translation_files | array[string] | I percorsi per eventuali file di output aggiuntivi. |
status | stringa | Lo stato di elaborazione corrente del file sorgente. |
upload_origin | stringa | Come è stato caricato il file (git, manual, api). |
created_at | stringa | Un timestamp ISO 8601 che indica quando è stato creato originariamente il file di origine. |
updated_at | stringa | Un timestamp ISO 8601 che indica quando il file sorgente è stato aggiornato l’ultima volta. |
file_tag | object | Informazioni sul tag di file. |
file_tag.id | intero | L’identificatore del tag file. |
file_tag.name | stringa | Il nome del tag file. |
download_url | stringa | L’URL per scaricare le traduzioni per questo file sorgente. |
Oggetto impaginazione:
| Campo | Tipo | Descrizione |
|---|---|---|
page | intero | Il numero di pagina corrente. |
per_page | intero | Il numero di elementi per pagina. |
total | intero | Il numero totale di file sorgente. |
total_pages | intero | Il numero totale di pagine. |
has_next_page | boolean | Se è disponibile una pagina successiva. |
has_previous_page | boolean | Se è 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_stringsParametri
| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
|---|---|---|---|---|
file_path | stringa | Sì | – | Il percorso del file di origine all’interno del progetto. |
file_tag_name | stringa | No | – | Il nome del tag di file. Se non fornito, viene utilizzato il tag predefinito del progetto. |
page | intero | No | 1 | Il numero di pagina per l’impaginazione (utilizzato come cursore). Deve essere maggiore di 0. |
q | stringa | No | – | La 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
| Campo | Tipo | Descrizione |
|---|---|---|
total_strings_count | intero | Il numero totale di stringhe traducibili nel file sorgente. |
translation_strings | array[object] | L’array di oggetti stringa di traduzione (impaginato, massimo 500 per pagina). |
translation_strings[].source | stringa | Il testo sorgente originale da tradurre. |
translation_strings[].translations | object | Un hash di traduzioni in cui le chiavi sono i codici ISO della lingua e i valori sono il testo tradotto. |
cursor | intero | Il 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
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
file_path | stringa | Sì | Il percorso in cui il file sorgente deve essere archiviato nel progetto. Deve avere un estensione supportata. |
output_file_path | stringa | Sì | Il modello di percorso di output per i file tradotti. Usa {{lang}} come placeholder per il codice della lingua. |
translations | array[object] | No | I 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_iso | stringa | Sì | Il 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[].file | file | Sì | Il file di traduzione da caricare. |
additional_translation_files | array[object] | No | Configurazioni 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[].type | stringa | Sì | Vedi formati di file supportati per maggiori dettagli. |
additional_translation_files[].path | stringa | Sì | Il 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
| Campo | Tipo | Descrizione |
|---|---|---|
source_file.id | intero | L’identificatore univoco per il file di origine creato. |
source_file.file_path | stringa | Il percorso del file di origine all’interno del progetto. |
source_file.created_at | stringa | Un timestamp ISO 8601 che indica quando è stato creato originariamente il file di origine. |
source_file.file_tag.id | intero | L’identificatore del tag file. |
source_file.file_tag.name | stringa | Il 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
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
file | file | Sì | Il 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_path | stringa | Sì | Il percorso del file di origine esistente nel progetto che deve essere aggiornato. |
file_tag_name | stringa | No | Il nome del tag di file associato al file di origine. Se non viene fornito, viene utilizzato il tag di file predefinito del progetto. |
callback_url | stringa | No | L’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
| Campo | Tipo | Descrizione |
|---|---|---|
source_file.id | intero | L’identificatore univoco per il file di origine elaborato. |
source_file.file_path | stringa | Il percorso del file di origine all’interno del progetto. |
source_file.created_at | stringa | Un timestamp ISO 8601 che indica quando è stato creato originariamente il file di origine. |
source_file.file_tag.id | intero | L’identificatore del tag file. |
source_file.file_tag.name | stringa | Il 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
- Prerequisito: Il file di origine deve essere già stato creato tramite Crea il file di origine.
- Caricamento file: Il nuovo contenuto viene caricato e sostituisce il contenuto del file esistente.
- Elaborazione: Le nuove stringhe traducibili vengono estratte e tradotte automaticamente.
- 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_statusParametri
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
file_path | stringa | Sì | Il percorso del file di origine all’interno del progetto. |
file_tag_name | stringa | No | Il 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
| Campo | Tipo | Descrizione |
|---|---|---|
translation_status.status | stringa | Lo stato di elaborazione attuale del file di origine. Vedi i valori di stato di seguito. |
translation_status.completeness | numero | La 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:
| Stato | Descrizione |
|---|---|
pending | Il file di origine è in attesa di essere elaborato. |
processing | La traduzione è attualmente in corso. |
completed | Tutte le traduzioni sono state completate. |
failed | Il 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
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
file_path | stringa | Sì | Il percorso del file di origine all’interno del progetto. |
file_tag_name | stringa | No | Il 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/zipContent-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_filese ignorato. - I file con formati non supportati sono elencati in
unsupported_filese ignorati. - Anche i file con contenuto non valido sono elencati in
unsupported_filese 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 richiestaPOSTper ogni file di origine elaborato con i relativi risultati.
Richiesta HTTP
POST https://app.ptc.wpml.org/api/v1/source_files/bulk
Parametri
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
zip_file | file | Sì | Un archivio ZIP contenente i file di origine da caricare. Deve essere un file ZIP valido. |
file_tag_name | stringa | No | Il 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_url | stringa | No | L’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
| Campo | Tipo | Descrizione |
|---|---|---|
success | boolean | Indica se l’operazione di caricamento in blocco è andata a buon fine. |
file_tag | object | Le informazioni del tag file. |
file_tag.id | intero | L’identificatore del tag file. |
file_tag.name | stringa | Il nome del tag file. |
processed_files | array[object] | Un array di file di origine che sono stati elaborati correttamente. |
processed_files[].id | intero | L’identificatore univoco per il file di origine creato. |
processed_files[].file_path | stringa | Il percorso del file di origine, preservando la struttura ZIP originale. |
processed_files[].created_at | stringa | Un timestamp ISO 8601 che indica quando è stato creato il file di origine. |
processed_files[].file_tag | object | Le informazioni del tag file. |
processed_files[].file_tag.id | intero | L’identificatore del tag file. |
processed_files[].file_tag.name | stringa | Il nome del tag file. |
unsupported_files | array[string] | Un array di nomi di file che non sono in un formato supportato. |
not_found_files | array[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`);