Introduction

Welcome to the Translation Proxy API consumer specification! You can use the information presented here to build an API that Translation Proxy is able to consume.

The Translation Proxy system allows WPML and Translation Services to communicate efficiently. Send jobs for translation and download completed translations. There is no direct communication between WPML and Translation Services.

Connecting

WPML has a common interface, that allows website admins to activate and authenticate with the Translation Service, select translatable content and send it to Translation Proxy.

Receiving

As soon as Translation Proxy delivers the data to the Translation Service, website admins are expected to login to the Translation Service client panel, and complete any additional configuration (select translators, accept bids, etc.) that may be required.

Delivering

When a translation is ready, Translation Service will send a notification to Translation Proxy to download the completed translation and deliver it to WPML.

Communication workflow

Here is an example of the communication workflow between Translation Proxy and Translation Service.

Communication workflow

To be able to send any data to a Translation Service, website admins are required to have an account with the Translation Service. WPML does not allow to create an account in Translation Services.

And of course, as already hinted, we also assume that as soon as Translation Proxy delivers all files for translation (from WPML to the Translation Service); website admins will complete any further configuration needed for translators to start their work in the Translation Service client panel.

General API Specifications

Translation Proxy communicates with APIs build based on the JSON:API specification. Use the documentation we provide here and the examples over at JSON:API to structure your API.

API endpoint format

Please note the format of the API endpoints. The URI can be divided into 3 distinct parts:

{api-base-url}/{api-version}/{api-endpoint}

For example for the "Authentication request" the parts are:

https://api.example.com/v1/clients

Key	Value
api-base-url	https://api.example.com
api-version	v1 - usually a version number (e.g. 1.0) in real world applications
api-endpoint	clients

Authentication

To authorize, Translation Proxy makes a GET request to a clients API endpoint:


RestClient.get(
  "https://example.com/api/clients",
  {
    accept:"application/vnd.api+json",
    authorization: "Token token=TPynCDt1oAvmyQnZT4Ep4TrI6VfGXgHWLcKa5fmNVaIt"
  }
)


curl "https://example.com/api/clients"
  -H "Authorization: Token token='TPynCDt1oAvmyQnZT4Ep4TrI6VfGXgHWLcKa5fmNVaIt'"
  -H "Accept: application/vnd.api+json"

Make sure to replace TPynCDt1oAvmyQnZT4Ep4TrI6VfGXgHWLcKa5fmNVaIt with your API key.

The above request must return a JSON structured response like this:

{
  "data": {
    "id": 1,
    "type": "users",
    "attributes": {
      "name": "John Doe"
    }
  }
}

When a website admin activates your Translation Service in WPML, he is asked to authorize the connection with a given API Token. Translation Proxy requests the client account with the provided API Token from your Translation Service.

If the request is successful then your Translation Service is connected to the WPML instance and the website admin is able to send content for translation.

Raise an error object when the request is unsuccessful

HTTP Request

GET https://example.com/api/clients

Request Headers

Key	Value
Authorization	Token token="TPynCDt1oAvmyQnZT4Ep4TrI6VfGXgHWLcKa5fmNVaIt"
Accept	application/vnd.api+json

Your Translation Service must provide a unique API Token to each client, and TP will do a base64 encode for the API Token before using it in the requests authorization header.

Language Pairs


RestClient.get(
  "https://example.com/api/language_pairs",
  {
    accept:"application/vnd.api+json",
    authorization: "Token token=#{api_token}"
  }
)


curl "https://example.com/api/language_pairs"
  -H "Authorization: Token token='$api_token'"
  -H "Accept: application/vnd.api+json"

The above request must return a JSON structured response array like this:

{
  "data":[{
    "id": "1",
    "type": "language-pairs",
    "attributes": {
       "source-language": {
          "name": "English",
          "iso-code": "en"
       },
       "target-language": {
          "name": "German",
          "iso-code": "de"
       }
     }
  },
  {
    "id": "2",
    "type": "language-pairs",
    "attributes": {
       "source-language": {
          "name": "German",
          "iso-code": "de"
       },
       "target-language": {
          "name": "English",
          "iso-code": "en"
       }
     }
  }]
}

To retrieve supported language pairs, Translation Proxy makes a GET request to a language_pairs API endpoint. Language pairs may be configured for all user accounts or per account.

Language Pair Arrangement

Should the language pairs be set globally (for all user accounts) the request will likely be redirected to a general language pair endpoint.

In the case where the language pairs are set per user account the API Token in the Authorization header will likely be used to redirect the request to the right language pair endpoint for the individual account.

Language Pair Direction

Each source and each target needs to be explicitly specified in the response. For example given a language e.g. "German" can used both as source and target language, the response will return information with "German" both in the source and target fields as shown in the example response to the right.

Raise an error object when the request is unsuccessful

HTTP Request

GET https://example.com/api/language_pairs

Request Headers

Key	Value
Authorization	Token token={api_token}
Accept	application/vnd.api+json

Please note the json structure of the expected response in the code examples column

Receiving Content

Create project


RestClient.post(
  "https://example.com/api/projects",
  {
    data: {
      type: 'project',
      attributes: {
        name: 'Example project name',
        deadline: unix_timestamp
      }
    }
  },
  {
    accept:"application/vnd.api+json",
    content_type: :json,
    authorization: "Token token=#{api_token}"
  }
)


curl -X POST "https://example.com/api/projects"
  -H "Authorization: Token token=$api_token"
  -H "Accept: application/vnd.api+json"
  -H "Content-Type: application/json"
  -d @- <<REQUEST_BODY
  {
    "data":{
      "type": "project",
      "attributes": {
        "name": "Example project name",
        "deadline": "$unix_timestamp"
      }
    }
  }
REQUEST_BODY

The above request must return a JSON structured response like this:

{
  "data": {
    "id": 1,
    "type": "projects",
    "attributes": {
      "name": "Example project name",
      "status": "created"
    }
  }
}

You may return more attributes. We are mainly showing those that are of interest to Translation Proxy. (status and name)

To initialize a translation project, Translation Proxy makes a POST request to a projects API endpoint

Raise an error object when the request is unsuccessful

HTTP Request

POST http://example.com/api/projects

Request Headers

Key	Value
Authorization	Token token={api_token}
Accept	application/vnd.api+json
Content-Type	application/json

Post Parameters

Parameter	Value	Description
name	string	The project name
deadline	integer	A suggested deadline as UNIX Timestamp

Please note the json structure of the expected response in the code examples column

Add file to project


RestClient.post(
  "https://example.com/api/jobs",
  {
    data: {
      type: 'jobs',
      attributes: {
        name: 'Example job name',
        source_language: 'iso_code',
        target_language: 'iso_code',
        file: 'xliff_file',
        file_type: 'xliff',
        callback_url: 'https://call-back-url?with_params=value&hash=value',
      },
      relationships: {
        project: {
          data: {
            type: 'project',
            id: "#{project_id_from_create_project_request}"
          }
        }
      }
    }
  },
  {
    accept:"application/vnd.api+json",
    content_type: :multipart_form,
    authorization: "Token token=#{api_token}"
  }
)


curl -X POST "https://example.com/api/jobs"
  -H "Authorization: Token token=$api_token"
  -H "Accept: application/vnd.api+json"
  -F @- <<REQUEST_BODY
    "data": {
      "type": "jobs'",
      "attributes": {
        "name": "Example job name",
        "source_language": "iso_code",
        "target_language": "iso_code",
        "file_type": "xliff",
        "callback_url": "https://call-back-url?with_params=value&hash=value",
      },
      "relationships": {
        "project": {
          "data": {
            "type": "project",
            "id": $project_id_from_create_project_request
          }
        }
      }
    }
    -F data['attributes']['file']=@file.xliff
REQUEST_BODY

The above request must return a JSON structured response like this:

{
  "data": {
    "id": 1,
    "type": "jobs",
    "attributes": {
      "status": "created"
    }
  }
}

You may return more attributes. We are mainly showing those that is of interest to Translation Proxy. (status)

To upload a translation job, Translation Proxy makes a POST request to a jobs API endpoint.

Raise an error object when the request is unsuccessful

HTTP Request

POST http://example.com/api/jobs

Request Headers

Key	Value
Authorization	Token token={api_token}
Accept	application/vnd.api+json
Content-Type	multipart/form-data

Post Parameters

Parameter	Value	Description
name	string	The job name
source_language	string	The source language iso code
target_language	string	The target language iso code
file	file	The xliff file
file_type	string	The file type. Defaults to `xliff`
callback_url	string	A url for notification callbacks
relationships - type	string	Defaults to `project`
relationships - id	integer	The project id

Please note the json structure of the expected response in the code examples column

Commit project


RestClient.patch(
  "https://example.com/api/projects/#{id}",
  {
    data: {
      type: 'projects',
      id: "#{project_id}",
      attributes: {
        status: 'ready'
      }
    }
  },
  {
    accept:"application/vnd.api+json",
    content_type: :json,
    authorization: "Token token=#{api_token}"
  }
)


curl -X PATCH "https://example.com/api/projects/$id"
  -H "Authorization: Token token=$api_token"
  -H "Accept: application/vnd.api+json"
  -H "Content-Type: application/json"
  -d @- <<REQUEST_BODY
  {
    "data":{
      "type": "projects",
      "id": $project_id,
      "attributes": {
        "status": "ready"
      }
    }
  }
REQUEST_BODY

The above request must return a JSON structured response like this:

{
  "data": {
    "id": 1,
    "type": "projects",
    "attributes": {
      "status": "ready"
    }
  }
}

You may return more attributes. We are mainly showing those that interest us. (status)

To commit a translation project, Translation Proxy makes a PATCH request to a projects API endpoint.

Raise an error object when the request is unsuccessful

HTTP Request

PATCH http://example.com/api/projects/:id

Request Headers

Key	Value
Authorization	Token token={api_token}
Accept	application/vnd.api+json
Content-Type	application/json

Post Parameters

Parameter	Value	Description
id	interger	The project id
status	string	The project status. Defaults to `ready`

Please note the json structure of the expected response in the code examples column

Delivering Content

Notifications


RestClient.post(
  "https://tp.api.url/service/notifications/#{suid}?hash=#{authentication_hash}",
  {
    data: {
      type: 'notification',
      attributes: {
        object_id: 'job_id',
        object_type: 'job',
        status: 'translation_ready'
      }
    }
  },
  {
    content_type: :json
  }
)


curl -X POST "https://tp.api.url/service/notifications/$suid?hash=$authentication_hash"
  -H "Content-Type: application/json"
  -d @- <<REQUEST_BODY
  {
    "data":{
      "type": "notification",
      "attributes": {
        "object_id": "$job_id",
        "object_type": "job",
        "status": "translation_ready",
      }
    }
  }
REQUEST_BODY

The callback_url was sent with the file upload request

To download a translated job or cancel a translation job, Translation Proxy expects a POST or GET notification callback. This is the callback url that was sent with the params during the add file to project request

HTTP Request

POST https://tp.api.url/service/notifications/:suid?hash=:authentication_hash

Request Headers

Key	Value
Content-Type	application/json

Post Parameters

Parameter	Value	Description
type	string	The callback type. Expects `notification`
object_id	integer	The resource id. The id returned in the response when the job was created.
object_type	string	The resource type. Expects `job`
status	string	The job status. Accepts `translation_ready` or `cancelled`

Please note the json structure of the expected response in the code examples column

Job Status


RestClient.get(
  "https://example.com/api/jobs/#{id}"
  {
    accept:"application/vnd.api+json",
    authorization: "Token token=#{api_token}"
  }
)


curl "https://example.com/api/jobs/$id"
  -H "Authorization: Token token=$api_token"
  -H "Accept: application/vnd.api+json"

The above request must return a JSON structured response like this:

{
  "data": {
    "type": "job",
    "attributes": {
      "name": "Example job name",
      "source_language": "iso_code",
      "target_language": "iso_code",
      "status": "translation_ready"
    },
    "relationships": {
      "translation": {
        "data": {
          "type": "translation",
          "id": 1
        }
      }
    }
  }
}

You may return more attributes. We are mainly showing those that are of interest to Translation Proxy. (status, relationships)

Before responding to a notification callback, Translation Proxy makes a GET request to a jobs/:id API endpoint to check the status of the job. Only a cancelled or translation_ready status will give permission to Translation Proxy to take further action - i.e. to download a completed translation or cancel a translation job.

Raise an error object when the request is unsuccessful

HTTP Request

GET http://example.com/api/jobs/:id

Request Headers

Key	Value
Authorization	Token token={api_token}
Accept	application/vnd.api+json

Please note the json structure of the expected response in the code examples column.

Download Translation


RestClient.get(
  "https://example.com/api/translations/#{id}"
  {
    accept:"application/vnd.api+json",
    authorization: "Token token=#{api_token}"
  }
)


curl "https://example.com/api/translations/$id"
  -H "Authorization: Token token=$api_token"
  -H "Accept: application/vnd.api+json"

The above request must return the translated content in the response body

To download a completed translation, Translation Proxy makes a GET request to a translations API endpoint

Raise an error object when the request is unsuccessful

HTTP Request

GET http://example.com/api/translations/:id

Request Headers

Key	Value
Authorization	Token token={api_token}
Accept	application/vnd.api+json

Confirm Delivery


RestClient.patch(
  "https://example.com/api/jobs/#{id}",
  {
    data: {
      type: 'jobs',
      id: "#{job_id}",
      attributes: {
        status: 'delivered'
      }
    }
  },
  {
    accept:"application/vnd.api+json",
    content_type: :json,
    authorization: "Token token=#{api_token}"
  }
)


curl -X PATCH "https://example.com/api/jobs/$id"
  -H "Authorization: Token token=$api_token"
  -H "Accept: application/vnd.api+json"
  -H "Content-Type: application/json"
  -d @- <<REQUEST_BODY
  {
    "data":{
      "type": "jobs",
      "id": $job_id,
      "attributes": {
        "status": "delivered"
      }
    }
  }
REQUEST_BODY

The above request must return a JSON structured response like this:

{
  "data": {
    "id": 1,
    "type": "jobs",
    "attributes": {
      "status": "delivered"
    }
  }
}

You may return more attributes. We are mainly showing what is of interest to Translation Proxy. (status)

To confirm a translation delivery, Translation Proxy makes a PATCH request to a jobs API endpoint

Raise an error object when the request is unsuccessful

HTTP Request

PATCH http://example.com/api/jobs/:id

Request Headers

Key	Value
Authorization	Token token={api_token}
Accept	application/vnd.api+json
Content-Type	application/json

Post Parameters

Parameter	Value	Description
id	interger	The job id
status	string	The job status. Defaults to `delivered`

Please note the json structure of the expected response in the code examples column