PTC

Carica e gestisci i file di origine tramite l'API

Usa questa API per caricare nuovi file di origine, sostituire quelli obsoleti, monitorare i progressi della traduzione e scaricare le traduzioni completate.

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

Come l'API di PTC identifica e organizza i file di origine

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

Tag del file

I tag del file sono un modo flessibile per raggruppare e organizzare i file di origine nei progetti di traduzione. Puoi usarli come categorie per adattarli alle esigenze del tuo flusso di lavoro. Ad esempio, i tag del file possono indicare:

  • 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 del file sono facoltativi nella maggior parte delle operazioni dell'API. Tuttavia, ogni file di origine ha sempre almeno un tag. Un tag del file predefinito viene creato e assegnato automaticamente quando si configura un progetto. Questo comportamento predefinito mantiene i progetti organizzati anche nelle configurazioni semplici, consentendoti comunque di creare strutture di tag più avanzate quando necessario.

Nome del tag del file + Percorso del file

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

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

Parametri di query

Durante il recupero di un file specifico, i relativi endpoint 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 di origine nel progetto

Elenca tutti i file di origine 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

Parametro Tipo Obbligatorio Predefinito Descrizione
page integer No 1 Il numero di pagina per l'impaginazione. Deve essere maggiore di 0.
per_page integer No 50 Il numero di elementi per pagina. Deve essere maggiore di 0.
order_by string No created_at Il campo in base al quale ordinare. Valori consentiti: id, created_at, updated_at.
sort string No desc La direzione dell'ordinamento. Valori consentiti: asc, desc.
file_path string No – Filtra per percorso del file esatto.
upload_origin string No – Filtra in base alla modalità di caricamento del file. I valori consentiti includono: git, manual, api.

Risposte

Risposta di successo

200 OKapplication/json
{
  "source_files": [
    {
      "id": 123,
      "file_path": "locales/en.po",
      "translation_path": "locales/{{lang}}.po",
      "additional_translation_files": ["locales/{{lang}}.mo"],
      "status": "completed",
      "upload_origin": "git",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T14:20:00.000Z",
      "file_tag": {
        "id": 456,
        "name": "frontend"
      },
      "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3,
    "has_next_page": true,
    "has_previous_page": false
  }
}
Schema della risposta

Oggetto file di origine:

Campo Tipo Descrizione
id integer L'identificatore univoco per il file di origine.
file_path string Il percorso del file di origine all'interno del progetto.
translation_path string Il modello che indica dove devono essere salvati i file tradotti.
additional_translation_files array[string] I percorsi per eventuali file di output aggiuntivi.
status string Lo stato di elaborazione attuale del file di origine.
upload_origin string La modalità di caricamento del file (git, manual, api).
created_at string Un timestamp ISO 8601 che indica quando il file di origine è stato creato originariamente.
updated_at string Un timestamp ISO 8601 che indica quando il file di origine è stato aggiornato per l'ultima volta.
file_tag object Informazioni sul tag del file.
file_tag.id integer L'identificatore del tag del file.
file_tag.name string Il nome del tag del file.
download_url string L'URL per scaricare le traduzioni per questo file di origine.

Oggetto impaginazione:

Campo Tipo Descrizione
page integer Il numero di pagina attuale.
per_page integer Il numero di elementi per pagina.
total integer Il numero totale di file di origine.
total_pages integer Il numero totale di pagine.
has_next_page boolean Indica se è disponibile una pagina successiva.
has_previous_page boolean Indica se è disponibile una pagina precedente.

Risposte di errore

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

Esempi di richiesta

Richiesta di base:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Esempi di codice

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get Translation Strings

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

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

Richiesta HTTP

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

Parametri

Parametro Tipo Obbligatorio Predefinito Descrizione
file_path string Sì – Il percorso del file di origine all'interno del progetto.
file_tag_name string No – Il nome del tag del file. Se non specificato, viene utilizzato il tag predefinito del progetto.
page integer No 1 Il numero di pagina per l'impaginazione (utilizzato come cursore). Deve essere maggiore di 0.
q string No – La query di ricerca per filtrare le stringhe di traduzione in base al loro testo di origine.

Risposte

Risposta di successo

200 OKapplication/json
{
  "total_strings_count": 1250,
  "translation_strings": [
    {
      "source": "Welcome to our application",
      "translations": {
        "es": "Bienvenido a nuestra aplicación",
        "fr": "Bienvenue dans notre application",
        "de": "Willkommen in unserer Anwendung"
      }
    },
    {
      "source": "Login",
      "translations": {
        "es": "Iniciar sesión",
        "fr": "Connexion",
        "de": "Anmelden"
      }
    }
  ],
  "cursor": 1
}
Schema della risposta
Campo Tipo Descrizione
total_strings_count integer Il numero totale di stringhe traducibili nel file di origine.
translation_strings array[object] L'array di oggetti delle stringhe di traduzione (paginato, max 500 per pagina).
translation_strings[].source string Il testo di origine originale da tradurre.
translation_strings[].translations object Un hash di traduzioni in cui le chiavi sono i codici ISO delle lingue e i valori sono i testi tradotti.
cursor integer Il cursore di pagina corrente utilizzato per la paginazione.

Risposte di errore

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

Richieste di esempio

Richiesta di base:

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

Una richiesta con tag del 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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Una richiesta con paginazione 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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Esempi di codice

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend&page=1&q=login" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Crea il file di origine

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

Questo endpoint crea la voce del file e configura la sua traduzione, ma non allega il contenuto effettivo del file.

Dopo aver creato il file, dovrai utilizzare l'endpoint Elabora il file di origine 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 string Sì Il percorso in cui il file di origine deve essere archiviato nel progetto. Deve avere un'estensione supportata.
output_file_path string Sì Il modello di percorso di output per i file tradotti. Usa {{lang}} come segnaposto per il codice della lingua.
file_tag_name string No Il nome del tag del file sotto cui registrare il file di origine. Se non fornito, viene utilizzato il tag del file predefinito del progetto.
translations array[object] No I file delle traduzioni preesistenti da caricare insieme al file di origine. Questi file verranno archiviati così come forniti e le loro stringhe non verranno ritradotte da PTC. Nota che fornire traduzioni esistenti non è consigliato, poiché PTC produce risultati migliori quando può utilizzare il contesto completo del tuo progetto e tradurre da zero.
translations[].target_language_iso string Sì Il codice ISO della lingua di destinazione per questa traduzione. Puoi trovare l'elenco completo delle lingue supportate e i relativi 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 dei file di output aggiuntivi 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 string Sì Vedi i formati di file supportati per maggiori dettagli.
additional_translation_files[].path string Sì Il modello di percorso per il file.

Risposte

Risposta di successo

201 Createdapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
Schema della risposta
Campo Tipo Descrizione
source_file.id integer L'identificatore univoco per il file di origine creato.
source_file.file_path string Il percorso del file di origine all'interno del progetto.
source_file.created_at string Un timestamp ISO 8601 che indica quando il file di origine è stato originariamente creato.
source_file.file_tag.id integer L'identificatore del tag del file.
source_file.file_tag.name string Il nome del tag del file.

Risposte di errore

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

Richieste di esempio

Creazione di base del file di origine:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{{lang}}.json" \
  -F "file_tag_name=frontend"

Create non accetta callback_url. La registrazione di un file di origine non avvia alcuna traduzione, quindi non c'è nulla che una callback debba annunciare: passalo invece a Elabora il file di origine o a Caricamento in blocco dei file di origine, che sono le chiamate che avviano il lavoro.

Richiesta con traduzioni preesistenti:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/messages.json" \
  -F "output_file_path=locales/{{lang}}/messages.json" \
  -F "translations[0][target_language_iso]=es" \
  -F "translations[0][file]=@spanish_translations.json" \
  -F "translations[1][target_language_iso]=fr" \
  -F "translations[1][file]=@french_translations.json"

Richiesta con file di output aggiuntivi:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/messages.po" \
  -F "output_file_path=locales/{{lang}}/messages.po" \
  -F "additional_translation_files[][type]=mo" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.mo" \
  -F "additional_translation_files[][type]=json" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.json"

Esempi di codice

  • JavaScript (FormData)
  • Python (requests)
  • PHP (cURL)
  • Node.js (axios)
  • Corpo della richiesta di callback
curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{{lang}}.json"
{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "frontend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=src/locales/en.json&file_tag_name=frontend",
  "file_path": "src/locales/en.json"
}

Elabora il file di origine

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

Questo endpoint sostituisce i contenuti attuali del file, aggiorna le stringhe traducibili archiviate e avvia la traduzione automatica.

Per usare questo endpoint, il file di origine deve già esistere nel progetto. Se non lo hai ancora creato, vedi Creare 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. I contenuti del file vengono convalidati per assicurare che corrispondano all'estensione del file dichiarata. Ad esempio, se l'estensione del file è .json, i contenuti caricati devono essere JSON valido.
file_path string Sì Il percorso del file di origine esistente nel progetto che deve essere aggiornato.
file_tag_name string No Il nome del tag del file associato al file di origine. Se non fornito, viene usato il tag del file predefinito del progetto.
callback_url string No L'URL che riceve le notifiche webhook al completamento dell'elaborazione del file.

Risposte

Risposta di successo

200 OKapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
Schema della risposta
Campo Tipo Descrizione
source_file.id integer L'identificatore univoco del file di origine elaborato.
source_file.file_path string Il percorso del file di origine all'interno del progetto.
source_file.created_at string Un timestamp ISO 8601 che indica quando il file di origine è stato originariamente creato.
source_file.file_tag.id integer L'identificatore del tag del file.
source_file.file_tag.name string Il nome del tag del file.

Risposte di errore

Formato del file non supportato o non valido

L'endpoint Elabora sostituisce i contenuti del file con quelli che carichi, quindi non c'è alcuna ricerca che possa fallire: questo endpoint non ha casi di 'non trovato'. L'unico rifiuto che restituisce riguarda il controllo dei contenuti sul file caricato.

422 Unprocessable Entity
{
  "success": false,
  "message": "Unprocessable Entity",
  "code": 422,
  "errors": [9001]
}

errors è un array di codici numerici, non un oggetto con chiavi di campo. 9001 significa che il contenuto non è stato interpretato nel formato dichiarato dalla sua estensione. Alcuni rifiuti includono anche un oggetto additional_info con i dettagli specifici.

Non autorizzato
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Accesso negato
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Flusso di lavoro

  1. Prerequisito: Il file di origine deve essere già stato creato tramite Creare il file di origine.
  2. Caricamento del 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: Al termine dell'elaborazione viene inviata una notifica webhook facoltativa.

Callback del webhook

Quando viene fornito un callback_url, PTC invierà una richiesta POST a quell'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"
}

Richieste di esempio

Elaborazione di base del file:

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend"

Richiesta con URL di callback:

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@messages.po" \
  -F "file_path=locales/messages.po" \
  -F "callback_url=https://your-app.com/webhooks/translation-complete"

Esempi di codice

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend" \
  -F "callback_url=https://your-app.com/webhooks/complete"

Formati di file supportati

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

Usa l'endpoint Elenca i formati di file supportati per ottenere l'elenco completo dei formati supportati.


Ottieni lo stato della traduzione

Recupera l'avanzamento attuale della traduzione per un file di origine specifico, indicando la percentuale di completamento e lo stato di elaborazione generale.

Questo è utile per:

  • Monitoraggio dei progressi – Monitorare l'avanzamento della traduzione per i job di lunga durata
  • Aggiornamenti dell'interfaccia utente – Mostrare le percentuali di completamento nella tua applicazione
  • Integrazione nel flusso di lavoro – Attivare azioni quando la traduzione raggiunge una determinata soglia

Richiesta HTTP

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

Parametri

Parametro Tipo Obbligatorio Descrizione
file_path string Sì Il percorso del file di origine all'interno del progetto.
file_tag_name string No Il nome del tag del file. Se non fornito, viene utilizzato il tag del file predefinito del progetto.

Risposte

Risposta di successo

200 OKapplication/json
{
  "translation_status": {
    "status": "completed",
    "completeness": 100
  }
}
Schema della risposta
Campo Tipo Descrizione
translation_status.status string Lo stato di elaborazione attuale del file di origine. Vedi i valori di stato di seguito.
translation_status.completeness number 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 degli errori.

Risposte di errore

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

Richieste di esempio

Richiesta di base:

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

Richiesta con tag del 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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Esempi di codice

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Scarica tutte le traduzioni

Scarica tutti i file tradotti per un file di origine specifico sotto forma di archivio ZIP.

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

Se non ci sono traduzioni disponibili 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 string Sì Il percorso del file di origine all'interno del progetto.
file_tag_name string No Il nome del tag del file. Se non fornito, viene utilizzato il tag del 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

200 OKapplication/zip202 AcceptedRetry-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. Di solito c'è una breve attesa tra il caricamento di un file di origine e la disponibilità delle traduzioni per il download.

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

Risposte di errore

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

Richieste di esempio

Richiesta di base:

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

Richiesta con tag del 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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -o frontend-translations.zip

Esempi di codice

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o translations.zip
# 200 -> saves the zip; 202 -> {"status":"processing","retry_after":N} (retry later);
# 404 -> {"error":"No translations are available for this source file"}

Caricamento in blocco dei file di origine

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 il 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 avviate 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 vengono elencati in unsupported_files e ignorati.
  • Anche i file con contenuto non valido vengono elencati in unsupported_files e ignorati.
  • Gli archivi di grandi dimensioni potrebbero richiedere più tempo per l'elaborazione. I file vengono elaborati uno alla volta per gestire le risorse, quindi è meglio dividere i caricamenti molto grandi (più di 100 file) in batch più piccoli. Tutti i file nell'archivio vengono impostati per la traduzione automatica.
  • Lo ZIP caricato deve essere valido e leggibile. Tutti i file al suo interno devono essere in un formato supportato. I nomi dei file non devono includere caratteri speciali che potrebbero causare problemi con i percorsi.
  • 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

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 string No Il nome del tag del file da associare a tutti i file di origine nell'archivio. Se non specificato, viene utilizzato il tag del file predefinito del progetto. Ogni file di origine è identificato in modo univoco dalla combinazione di file_path e file_tag_name.
callback_url string 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 delle directory viene preservata 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

200 OKapplication/json
{
  "success": true,
  "file_tag": {
      "id": 456,
      "name": "backend"
  },
  "processed_files": [
    {
      "id": 123,
      "file_path": "locales/messages-en.po",
      "created_at": "2024-01-15T10:30:00.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    },
    {
      "id": 124,
      "file_path": "locales/validation-en.po",
      "created_at": "2024-01-15T10:30:05.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    }
  ],
  "unsupported_files": [
    "readme.txt",
    "config.ini"
  ],
  "not_found_files": ["frontend/not-found-en.json"]
}
Schema della risposta
Campo Tipo Descrizione
success boolean Indica se l'operazione di caricamento in blocco ha avuto esito positivo.
file_tag object Le informazioni sul tag del file.
file_tag.id integer L'identificatore del tag del file.
file_tag.name string Il nome del tag del file.
processed_files array[object] Un array di file di origine elaborati con successo.
processed_files[].id integer L'identificatore univoco del file di origine creato.
processed_files[].file_path string Il percorso del file di origine, che preserva la struttura originale dello ZIP.
processed_files[].created_at string Un timestamp ISO 8601 che indica quando è stato creato il file di origine.
processed_files[].file_tag object Le informazioni sul tag del file.
processed_files[].file_tag.id integer L'identificatore del tag del file.
processed_files[].file_tag.name string Il nome del tag del 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 a nessun file di origine esistente e sono stati ignorati.

Risposte di errore

File ZIP non valido

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

Elaborazione non riuscita

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

Non autorizzato

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

Accesso negato

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

Callback webhook

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": "locales/messages-en.po"
}

Richieste di esempio

Caricamento in blocco di base:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend"

Richiesta con URL di callback:

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

Esempi di codice

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend" \
  -F "callback_url=https://your-app.com/webhooks/complete"
Successivo:

Trova i formati di file e le lingue di destinazione supportati tramite l'API →