API Guide

The API guide lists all steps necessary (or optional) to create a translation in contenthub. There are two types of translations: Standard and Instant. In addition, it is possible to order post-editing for an instant translation. The steps are listed in chronological order for each variant. For more details on objects, properties and endpoints, see the relevant documentation. There are two different variants of a translation: Standard and Instant. In addition, post-editing can be requested in advance for an instant translation for all languages, or for individual languages after an instant translation has been completed.

  1. Standard translation
  2. Instant translation
    1. Instant translation
    2. Post-editing after translation (Optional)
    3. Post-Editing specified in advance

1. Standard translation

1.1. Login

For login please see the example documentation for cURL: Authentication

1.2. Upload document(s) for translation

Now you need to upload your documents you want to translate. You have several possibilities to upload documents please check the documents - specification for details. In this example we use the URI upload:

POST /rest/api/documents HTTP/1.1

{
  "filename": "Lorem_ipsum.docx",
  "contentUri": "http://example.com/files/574d3526f342e39b88e5d414"
}

The response is the document:

{
  "id": "59a69d085606ba0007de6f50",
  "filename": "Lorem_ipsum.docx",
  "length": 4461,
  "uploadDate": "2016-07-30T11:10:00.184Z",
  "chunkSize": 261120,
  "md5": "24c1750c14fcfdaabbbdb5150835fcb5"
}

We need the document id in the next step.

1.3. Configure and create a standard translationTask

Now create a standard translationTask.

Example Request:

POST /rest/api/translationTasks HTTP/1.1

{
  "source": "de-DE",
  "target": "en-GB",
  "projectId": "57d830ba0f620b2c4ab206db"
}

The response is the created translationTask. Please use the id of the translationTask for any further operation. The translationTask id should be also stored in the system that implements the connector, because it is the unique identifier which refers to the sent translation inside the client system.

Example Response:

{
  "id": "5804c3d5ffd16c59fd02d8a0",
  "source": "de-DE",
  "target": "en-GB",
  "createdAt": "2016-10-17T12:28:04.955+0000",
  "desiredDeadline": null,
  "complete": false,
  "email": "api-user@example.tld",
  "progress": "NEW",
  "projectId": "57d830ba0f620b2c4ab206db"
}

Please see translationTask documentation for details.

1.4. Refer the uploaded documents as source documents to a translationTask

We use the document id to refer the document as source document to our created translationTask. You can either use the /translationTask/:id/sourceDocuments endpoint to do it, or you simply patch the translationTask:

Example Request:

PATCH /rest/api/translationTasks/:id HTTP/1.1

{
  "sourceDocumentIds": ["59a69d085606ba0007de6f50"]
}

You can also skip this step by simply provide the sourceDocumentIds in Step 3 like that:

Example Response:

POST /rest/api/translationTasks HTTP/1.1

{
  "source": "de-DE",
  "target": "en-GB",
  "projectId": "57d830ba0f620b2c4ab206db",
  "sourceDocumentIds": ["5804c2afffd16c59fd02d89e"]
}

1.5. Complete translation task and wait for quotes

To finish your translationTask configuration you need to set it to "complete". To do so just change the "complete" property of the translationTask from false to true.

Example Request:

PATCH /rest/api/translationTasks/:id HTTP/1.1

{
  "complete": true
}

Now the system automatically creates quote enquiries for the configured vendors. And you can expect quotes soon.

1.6. Ask for quotes (already commited and open quotes)

You can simply pull the quotes endpoint of a translationTask to receive all quotes. Also you can pull the quoteEnquiries endpoint of a translationTask to check how many quotes you can expect.

Check for already commited quotes:

Example Request:

GET /rest/api/translationTasks/:id/quotes HTTP/1.1

{
  "complete": true
}

Example Response:

[
  {
    "connectorQuoteId": "5891a7d00f62c3637782b978",
    "connectorEnquiryId": "5891a7b70f62c3637782b976",
    "createdAt": "2017-02-01T09:18:16.471Z",
    "number": "43949",
    "price": {
      "netAmount": "429.31",
      "vatPercentage": "19.0",
      "currency": "EUR",
      "vatAmount": "81.57",
      "grossAmount": "510.88"
    },
    "supplierName": "Test 24translate GmbH",
    "state": "OFFERED",
    "tapQuoteEnquiryId": "SYHNj2hZDTKBBQnPn",
    "id": "5891a7d802dde409d133ae51"
  },
  {
    "connectorQuoteId": "7276d72c-b50f-430f-880d-a73d45a0719b",
    "connectorEnquiryId": "5891a7c80f62d543d66b2ab2",
    "createdAt": "2017-02-01T09:18:16.641Z",
    "number": "MOCK-0fb643e7-9aed-42e0-9757-3fee9d26aea9",
    "price": {
      "netAmount": "587.73",
      "vatPercentage": "19",
      "currency": "EUR",
      "vatAmount": "111.67",
      "grossAmount": "699.40"
    },
    "supplierName": "Wieners + Wieners",
    "state": "OFFERED",
    "tapQuoteEnquiryId": "TGpbfP9d73PMtw6XZ",
    "id": "5891a7d802dde409d133ae56"
  }
]

Check for available quote enquiries:

GET /rest/api/translationTasks/:id/quoteEnquiries HTTP/1.1

Example Response:

[
  {
    "createdAt": "2017-02-01T08:15:02.010Z",
    "authorizationKey": "6171d2f4-acf0-4d91-8ce8-60f7c3465a4a",
    "lspVendorId": "579f5bdc0f6215543b5f5861",
    "lspVendorName": "Test 24translate GmbH",
    "translationTaskId": "uCbrmmRige6sTnXju",
    "enquiryId": "5891a7b70f62c3637782b976",
    "quotesFetched": true,
    "id": "SYHNj2hZDTKBBQnPn"
  },
  {
    "createdAt": "2017-02-01T08:15:02.010Z",
    "authorizationKey": "d0f579f0-0538-45d6-9de6-649631d8745d",
    "lspVendorId": "zbWp3XMAjuHxesKd3",
    "lspVendorName": "Wieners + Wieners",
    "translationTaskId": "uCbrmmRige6sTnXju",
    "enquiryId": "5891a7c80f62d543d66b2ab2",
    "quotesFetched": true,
    "id": "TGpbfP9d73PMtw6XZ"
  }
]

When the quotes are committed you will also see the quotes reference in the translationTask:

{
  "createdAt": "2017-02-01T09:18:16.643Z",
  "source": "de",
  "target": "fr",
  "desiredDeadline": "2017-02-03T09:00:00.000Z",
  "complete": true,
  "email": "api-user@example.tld",
  "sourceDocumentIds": [
    "5891a7a6883834000bfe8138"
  ],
  "quoteIds": [
    "5891a7d802dde409d133ae51",
    "5891a7d802dde409d133ae56",
    "5891a7d802dde409d133ae58"
  ],
  "progress": "TASK_COMPLETE",
  "projectId": "RJ3K7xW4axLWn5pGE",
  "id": "uCbrmmRige6sTnXju"
}

1.7. Accept and/or Reject quotes

To accept or reject quotes simply set the state of the quote you want to accept/reject. Please note that when you accept one quote, all other quotes will be rejected automatically.

Example Request:

PATCH /rest/api/quotes/:id HTTP/1.1

{
  "state": "ACCEPTED"
}

Please see quotes documentation for details. When a quote is accepted you can not change the state anymore to REJECTED.

The vendor gets notified automatically and the translation will be started. Now you just need to wait for the finished translation.

1.8. Download target documents

When the translation is delivered, the progress of the translationTask changes to TRANSLATION_DELIVERED.

Example Response:

{
  "createdAt": "2017-01-24T17:54:07.763Z",
  "source": "en",
  "target": "pl",
  "desiredDeadline": "2017-01-30T08:00:00.000Z",
  "complete": true,
  "email": "api-user@example.tld",
  "sourceDocumentIds": [
    "5835d98ed523ad00204d1358",
    "5835d96bd523ad00204d1354",
    "588604f72331ab000aa06f81",
    "58860876ea3d5e000b920577"
  ],
  "quoteIds": [
    "58888d1c02dde40267d2dd06",
    "58888d1c02dde40267d2dd0b"
  ],
  "progress": "TRANSLATION_DELIVERED",
  "projectId": "RJ3K7xW4axLWn5pGE",
  "id": "AQT4Dn6YJRwGCpnue"
}

Simply pull the translationTask/:id endpoint to check the progress. Now you can download the translations. To do so use the translationTask/:id/targetDocuments/content endpoint and you will receive all targetDocuments as a zip-archive.

Example Request:

GET /rest/api/translationTasks/:id/targetDocuments/content HTTP/1.1

To receive the documentIds you can pull the translationTask/:id/targetDocuments endpoint:

Example Request:

GET /rest/api/translationTasks/:id/targetDocuments HTTP/1.1

Example Response:

[
  {
    "filename": "test.xlf",
    "aliases": null,
    "chunkSize": 261120,
    "uploadDate": "2017-01-25T13:40:08.827Z",
    "length": 36867,
    "contentType": "application/x-xliff+xml",
    "md5": "1b554cfb7aadded9fda20fbc60eb4803",
    "createdAt": "2017-01-25T13:40:08.827Z",
    "id": "5888aab802dde40267d45581"
  },
  {
    "filename": "test2.xlf",
    "aliases": null,
    "chunkSize": 261120,
    "uploadDate": "2017-01-25T13:40:09.205Z",
    "length": 771283,
    "contentType": "application/x-xliff+xml",
    "md5": "c237cbef12fac2cde1f0aa79ee81c308",
    "createdAt": "2017-01-25T13:40:09.205Z",
    "id": "5888aab902dde40267d45583"
  }
]

When no documents are available the response is an empty array.

2. Instant translation

Variant A: Instant translation

1. Login

For login please see the example documentation for cURL: Authentication.

2. Configure and create an instant translationTask

Now create an instant translationTask. In contrast to the standard translation, the property features of the type array is required. The instant element is used for an instant translation.

Example Request:

POST /rest/api/translationTasks HTTP/1.1

{
  "source": "de-DE",
  "target": ["en-GB"],
  "features": [
    "instant"
  ],
  "sourceText": "This is a simple instant translation.",
  "projectId": "57d830ba0f620b2c4ab206db"
}

The response is the created translationTask. Important is the sourceDocumentIds property. The sourceText property from the request is converted to a .txt file. The file ID is now available in the sourceDocumentIds property of the translationTask.

Example Response: Excerpt of the response for simplification.

{
  "id": "5804c3d5ffd16c59fd02d8a0",
  "source": "de-DE",
  "target": ["en-GB"],
  "createdAt": "2016-10-17T12:28:04.955+0000",
  "desiredDeadline": null,
  "complete": false,
  "email": "api-user@example.tld",
  "progress": "NEW",
  "features": [
    "instant"
  ],
  "sourceDocumentIds": [
    "ae04aa18cd63c42c0d6c"
  ],
  "projectId": "57d830ba0f620b2c4ab206db"
}

Please see translationTasks documentation for more details.

3. Mark the translationTask as "complete"

To finish the configuration of the TranslationTask, the complete property must be set from false to true.

Example Request:

PATCH /rest/api/translationTasks/:id HTTP/1.1

{
  "complete": true
}

After setting the translationTask to complete, the documents are translated and delivered automatically. Further intervention is therefore not necessary.

4. Wait for the delivery and download target documents

See step 8. Download target documents for a standard translation.

Variant B: Post-editing after translation

1. Start the Post-Editing process

The starting point for a post-editing is a finished instant translation. To order a post editing for a single language, copy the ID of the corresponding delivery GET /rest/api/translationTasks/{id}/translationDeliveries and use it for the following request PATCH /rest/api/translationDeliveries/{delivery_id}.

Example Request:

PATCH /rest/api/translationDeliveries/:delivery_id HTTP/1.1

{
  "postediting": true
}

The translationTask then behaves like a standard translation. quotesEnquiries are generated and quotes must be accepted.

Variant C: Translation with Post-Editing specified in advance

1. Login

For login please see the example documentation for cURL: Authentication.

2. Configure and create an instant translation with Post-Editing

Now create an instant translationTask. In contrast to the standard translation, the property features of the type array is required. The elements instant and withPostEditing element are used for an instant translation.

Example Request:

POST /rest/api/translationTasks HTTP/1.1

{
  "source": "de-DE",
  "target": ["en-GB"],
  "features": [
    "instant",
    "withPostEditing"
  ],
  "sourceText": "This is a simple instant translation.",
  "projectId": "57d830ba0f620b2c4ab206db"
}

The response is the created translationTask. Important is the sourcedocumentIds property. The sourceText property in converted to an .txt file. The file ID is now available in the sourceDocumentIds property of the translationTask.

Example Response: Excerpt of the response for simplification.

{
  "id": "5804c3d5ffd16c59fd02d8a0",
  "source": "de-DE",
  "target": ["en-GB"],
  "createdAt": "2016-10-17T12:28:04.955+0000",
  "desiredDeadline": null,
  "complete": false,
  "email": "api-user@example.tld",
  "progress": "NEW",
  "features": [
    "instant",
    "withPostEditing"
  ],
  "sourceDocumentIds": [
    "ae04aa18cd63c42c0d6c"
  ],
  "projectId": "57d830ba0f620b2c4ab206db"
}

Please see translationTask documentation for more details.

3. Complete translation task and wait for quotes

See step 5. Complete translation task and wait for quotes for a standard translation.

4. Ask for quotes (already commited and open quotes)

See step 6. Ask for quotes (already commited and open quotes) for a standard translation.

5. Accept and/or reject quotes

See step 7. Accept and/or reject quotes for a standard translation.

6. Download target documents

See step 8. Download target documents for a standard translation.