PTC

Request and Retrieve Translations via the API

Use this API to send content for translation, track its progress, and retrieve the translations in all target languages.

This API accepts JSON-structured content, preserving the original structure and keys. It translates only text values, leaving numbers, booleans, nulls, and other non-text values unchanged.

Create Content Translations

Creates a new translation job from JSON-structured data.

The endpoint preserves your content’s original hierarchy of keys and arrays, translating only text values while leaving numbers, booleans, nulls, and other non-text values unchanged.

It is especially useful for:

  • Content management – Localizing dynamic content structured in JSON
  • Configuration files – Translating user-facing strings in config data
  • API responses – Translating structured response payloads
  • Documentation – Localizing hierarchical help content or guides

For a complete Rails implementation of this workflow, see translating dynamic content in Rails using the PTC API.

HTTP Request

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

Parameters

Parameter Type Required Description
data object Yes The JSON-structured data to translate. It can include nested objects, arrays, and string values.
name string No A human-readable name for the translation job. If omitted, one is generated automatically.
callback_url string No The URL that receives webhook notifications when the translation is complete.
target_languages array[string] No The array of ISO codes for target languages. If omitted, translations are created for all project-configured languages. See the Available Target Languages API for more information.

Request Body Example

{
  "data": {
    "app": {
      "title": "My Application",
      "navigation": {
        "home": "Home",
        "about": "About Us",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Save",
        "cancel": "Cancel",
        "submit": "Submit"
      },
      "messages": {
        "welcome": "Welcome to our platform",
        "error": "An error occurred"
      }
    },
    "version": "1.0.0",
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  },
  "name": "App UI Translations",
  "callback_url": "https://your-app.com/webhooks/translation-complete",
  "target_languages": ["es", "fr", "de"]
}

Responses

Success Response

201 Createdapplication/json
{
  "id": 123,
  "name": "App UI Translations",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

Response Schema

Field Type Description
id number The unique identifier of the content translation job.
name string The job name (auto-generated if not provided).
status string The current job status (queued, processing, completed).
created_at string The ISO 8601 timestamp indicating when the job was created.
updated_at string The ISO 8601 timestamp indicating when the job was last updated.

Error Responses

Invalid JSON Data
422 Unprocessable Entity
{
  "errors": {
    "data": ["Data must be a valid JSON object"]
  }
}
Invalid Target Languages
422 Unprocessable Entity
{
  "errors": {
    "target_languages": ["Language codes [zh, xx] are not configured for this project"]
  }
}
Unauthorized
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Forbidden
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

JSON Data Processing

When working with JSON-structured data, PTC processes the data as follows:

  • Structure is preserved – The original hierarchy of keys and nesting remains unchanged
  • Only strings are translated – Numbers, booleans, arrays, and null values are kept as they are
  • Path-based translation – Each translatable string is identified by its JSON path
  • Supports nesting – Works with deeply nested objects and arrays
  • Handles mixed data types – Non-string values are preserved without modification

Example Data Transformation

Input:

{
  "user": {
    "name": "Welcome User",
    "settings": {
      "theme": "Choose Theme",
      "count": 5,
      "enabled": true
    }
  }
}

Processing outcome:

  • user.name: “Welcome User” → Gets translated
  • user.settings.theme: “Choose Theme” → Gets translated
  • user.settings.count: 5 → Remains unchanged
  • user.settings.enabled: true → Remains unchanged

Translation Workflow

  1. Validation: JSON structure and target languages are checked
  2. Source file preparation: JSON is converted to an internal source format
  3. String reuse through translation memory: All translatable strings are extracted and stored in your project’s translation memory so previous translations can be reused
  4. Job queuing: A job is queued for each target language
  5. Processing: Automatic translation runs on the extracted strings
  6. Callback (optional): A webhook is sent when all translations are completed, if callback_url is provided

Webhook Callback

When a callback_url is provided, a POST request is sent when the job is completed.

Callback request body:

{
  "id": 1,
  "status": "completed",
  "translations_url": "https://app.ptc.wpml.org/api/v1/content_translation/1"
}

Supported Data Types

JSON Type Translation Behavior
string Translated to target languages
number Preserved as-is
boolean Preserved as-is
null Preserved as-is
array Processed recursively
object Processed recursively

Example Requests

Basic JSON translation:

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "welcome": "Welcome",
      "buttons": {
        "save": "Save",
        "cancel": "Cancel"
      }
    },
    "name": "UI Labels"
  }'

With specific target languages:

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "title": "Product Catalog",
      "categories": {
        "electronics": "Electronics",
        "clothing": "Clothing"
      }
    },
    "target_languages": ["es", "fr"],
    "callback_url": "https://myapp.com/webhook"
  }'

Code Examples

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"app":{"title":"My Application","navigation":{"home":"Home","about":"About Us"}}},"name":"App Translations","target_languages":["es","fr","de"],"callback_url":"https://your-app.com/webhooks/complete"}'

# The response includes the job "id". Poll its status (status stays
# "in_progress" until done — it is not set on the create response):
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/CONTENT_TRANSLATION_ID/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get Content Translations

Retrieves the original content and all translated versions for a specific content translation job.

The response preserves your input structure: it returns a source object plus one object per target language (keyed by language code such as es, fr, de).

HTTP Request

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}

Path Parameters

Parameter Type Required Description
id integer Yes The unique identifier of the content translation job to retrieve.

Responses

Success Response

200 OKapplication/json
{
  "source": {
    "app": {
      "title": "My Application",
      "navigation": {
        "home": "Home",
        "about": "About",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Save",
        "cancel": "Cancel"
      }
    }
  },
  "es": {
    "app": {
      "title": "Mi Aplicación",
      "navigation": {
        "home": "Inicio",
        "about": "Acerca de",
        "contact": "Contacto"
      },
      "buttons": {
        "save": "Guardar",
        "cancel": "Cancelar"
      }
    }
  },
  "fr": {
    "app": {
      "title": "Mon Application",
      "navigation": {
        "home": "Accueil",
        "about": "À propos",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Enregistrer",
        "cancel": "Annuler"
      }
    }
  }
}

Response Schema

Field Type Description
source object The original source content in the same nested structure as submitted.
{language_code} object The translated content for each target language, keyed by its ISO code (for example es, fr, de), with the same structure as source. For more information, see the Available Target Languages API.

Error Responses

Content Translation Not Found
404 Not Found
{
  "error": "Content translation not found"
}
Unauthorized
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Forbidden
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Example Requests

Basic request:

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Code Examples

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get the Content Translation Status

Retrieves the current status of a specific content translation job.

The response reflects the overall progress and includes whether the translation is queued, in progress, completed, or has failed.

HTTP Request

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status

Path Parameters

Parameter Type Required Description
id integer Yes The unique identifier of the content translation job to check.

Responses

Success Response

200 OKapplication/json
{
  "status": "completed",
  "completeness": 100
}
Response Schema
Field Type Description
status string The current translation status. Possible status values include: queued, in_progress, completed, failed, status_unknown.
completeness number The percentage of translated strings (0–100). Calculated as (completed_translatable_strings / total_translatable_strings) × 100.
Status Values
Status Description
queued The translation has been queued and is waiting to be processed.
in_progress The translation is currently being processed.
completed The translation has been completed successfully.
failed The translation has failed due to an error.
status_unknown The translation status is unknown or cannot yet be determined.

Error Responses

404 Not Found

Possible causes:

  • No content translation exists with the specified ID
  • The translation job does not belong to the authenticated project

Example

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "status": "completed",
  "completeness": 100
}

Response while the job is still running:

{
  "status": "in_progress",
  "completeness": 70
}
{
  "status": "completed",
  "completeness": 100
}