HomeGuidesAPI Reference

Create a Translation Request

Send the content you need to translate.

For creating a Translation request we offer two options: Posting a Translation Request or Posting a Quote Request.

If you intend to create particularly large or small requests, please take a look at our sizing guide.

If you have code, escaped or not escaped html, newlines or other special characters in your source text, please take a look at Special characters, encoding and newlines

  • Translation Request

    Posting a Translation Request orders the texts you have included within the request attribute. Please note that whenever using paid languages the order will be automatically charged to you. You can always do some testing for free with Tolq Latin (tq).

  • Quote Request

    If you prefer to check the content and the price beforehand in the clients application, you should create a Quote Request which works exactly the same except from the fact you have to add `/quote` at the end of the url and you will be able to review it before they are ordered. They can be ordered both from the UI and via our API.

Before you start making requests, you should take the limits of the API and how the content is split among translators into account. This will help you to optimise the results so they will meet your expectations.

Example

Let's suppose you need to translate an article in your CMS which has a title, an introduction, and a body of text.

Seeing as this is your first order, and you want to have it handled automatically, you decide to order it Posting a Translation Request and using Tolq Latin as the target language, which is free to test things out.

In this first request you would send this JSON:

{
  "request": {
        "title": {
          "text": "The example",
        },
        "intro": {
        	"text": "An example on how to use Tolq"
        },
    		"body": {
       		"text": "Tolq is a platform that allows you easily translate lots of content."
        }
    },
    "source_language_code": "en",
    "target_language_codes": "tq",
    "quality": "machine"
}

The server would answer back with this response:

{
  "id" : 1,
  "name" : null,
  "slug" : "untitled-1",
  "context_url" : null,
  "description" : null,
  "created_at" : "2016-03-02T10:23:32.441Z",
  "completed_at" : null,
  "quality" : "machine",
  "target_language_code" : "tq",
  "style_guide_reference_id" : 1,
  "status" : "pending"
}

If the request is made successfully, you will get a response with some useful data like the id. You will be able to use the id to retrieve a Translation Request. You can also use it to search and/or identify the request in the clients application. Or you can use this id to identify a callback later. For an overview of the possible states, see the status section to learn about the lifetime of a translation request.

Metadata per item

Each item that you wish to translate consists of a JSON object. The text property contains the content that you'd like to have translated. There are a few other properties that you can use for metadata:

  • commonmark: Boolean property. If the value is true, the contents will be considered to have the markdown (in the commonmark standard). Markdown will not be detected automatically.
  • html: Boolean property. If the value is true, the contents will be considered to be HTML content. This means that the HTML document will be parsed, and only translatable content will be sent to the translator, instead of the entire document. HTML will be detected automatically - this property overrides the autodetection. Marking plain text as HTML content has no adverse effects.