HTTP API

Machine translation

To harness the capabilities of machine translation via our HTTP API, it's essential to include hints in your primary content request. These hints serve as directives to inform the system of how machine translation should be executed, as well as to specify the extent to which it should be applied.

For scenarios where you already have translated content and need only post editing services, see the Post editing only section below.

Hints

The hint you'll need to add is of type machine-translation. It's important to remember that the machine-translation hint is exclusively applicable to fields of the localizable type. You'll also need to specify a policy, which outlines the details of how machine translation will be performed and what subsequent actions, if any, will follow after the automatic translation process.

Argument	Description
`policy`	Which policy to use.

Policies

Currently available policies for machine translation are:

Policy	Description
`none`	Special policy to indicate that no machine translation is requested, acts as the default value for a content request. Can also be specified on a field to avoid machine translating it if the request has a default policy.
`only-mt`	Request only automatic translation. The incoming `value` of fields will be machine translated and be made available as `value`.
`with-post-edit-light`	Provides a swift machine translation, followed by a 'good enough' human post-edited version later. The machine translated value will be made available on the field as `intermediateValue` and `value` will not be present until post editing is done.
`with-post-edit-full`	Provides a swift machine translation, followed by a 'close-to-human' post-edited version later. The machine translated value will be made available on the field as `intermediateValue` and `value` will not be present until post editing is done.
`with-full-rewrite`	Provides a swift machine translation, followed by a human localized version later. The machine translated value will be made available on the field as `intermediateValue` and `value` will not be present until localization is done.
`only-automatic`	Legacy - kept for reference - same as "`only-mt`" above.
`with-post-editing`	Legacy - kept for reference - same as "`with-post-edit-light`" above.

Examples

Activating only machine translation for the content request:

{
  ...,
  "hints": [
    {
      "type": "machine-translation",
      "policy": "only-mt"
    }
  ],
  "fields": [
    ...
  ],
  ...
}

Activating machine translation with post editing for the content request:

{
  ...,
  "hints": [
    {
      "type": "machine-translation",
      "policy": "with-post-edit-light"
    }
  ],
  "fields": [
    ...
  ],
  ...
}

Post editing only

For scenarios where you have already translated content (either machine translated or human translated) and need only post editing services, use the pre-translated hint type. This workflow skips the machine translation step and sends your pre-translated content directly for human post editing.

Pre-translated hints

When using pre-translated content, use the pre-translated hint type with the appropriate policy:

Argument	Description
`type`	Must be `"pre-translated"`
`policy`	Which post editing policy to use

Post editing policies

Available policies for pre-translated content:

Policy	Description
`only-light-editing`	Applies light post editing to pre-translated content for a 'good enough' quality level
`only-full-editing`	Applies comprehensive post editing to pre-translated content for 'close-to-human' quality level

Pre-translated field structure

When submitting pre-translated content, fields must include both the original source text and your translated version:

Field Property	Description
`originalValue`	The original source text before translation
`value`	Your pre-translated target text that will be post edited

Complete example

Here's a complete example for submitting pre-translated content for light post editing:

{
  "type": "standard",
  "language": {
    "source": "sv-SE",
    "target": "en-GB"
  },
  "hints": [
    {
      "type": "pre-translated",
      "policy": "only-light-editing"
    }
  ],
  "fields": [
    {
      "id": "url",
      "type": "context",
      "data": "string",
      "value": "https://test.url"
    },
    {
      "id": "id",
      "type": "internal",
      "data": "string",
      "value": "18481"
    },
    {
      "id": "name",
      "type": "localizable",
      "data": "string",
      "originalValue": "Anthon Berg Opera Choco Storpack",
      "value": "Anthon Berg Opera Choco Big Pack"
    },
    {
      "id": "description",
      "type": "localizable",
      "data": "html",
      "originalValue": "<p>Dessa chokladpraliner med smak av choco är en skapelse som kommer att få dina smaklökar att dansa.</p>",
      "value": "<p>These choco flavored chocolate pralines are a creation that will make your taste buds dance.</p>"
    }
  ]
}

Post editing workflow responses

Initial response

After submitting a pre-translated content request, you'll receive an immediate response with state: "pending":

{
  "source": "api",
  "language": { "source": "sv-SE", "target": "en-GB" },
  "created": "2023-09-25T13:16:12.000Z",
  "lastStateChange": "2023-09-25T13:16:23.000Z",
  "id": "sOuYRDrk9C6",
  "previous": null,
  "type": "standard",
  "state": "pending",
  "fields": [
    {
      "id": "name",
      "data": "string",
      "type": "localizable",
      "originalValue": "Anthon Berg Opera Choco Storpack",
      "value": "Anthon Berg Opera Choco Big Pack"
    }
  ],
  "hints": [
    {
      "type": "pre-translated",
      "policy": "only-light-editing"
    }
  ]
}

During post editing

When post editing begins, the state changes to confirmed and your pre-translated content is available:

{
  "state": "confirmed",
  "fields": [
    {
      "id": "name",
      "data": "string",
      "type": "localizable",
      "originalValue": "Anthon Berg Opera Choco Storpack",
      "intermediateValue": "Anthon Berg Opera Choco Big Pack"
    }
  ]
}

After post editing completion

When post editing is complete, the state changes to completed and the final edited content is available:

{
  "state": "completed",
  "completed": "2023-09-25T13:19:45.668Z",
  "fields": [
    {
      "id": "name",
      "data": "string",
      "type": "localizable",
      "originalValue": "Anthon Berg Opera Choco Storpack",
      "intermediateValue": "Anthon Berg Opera Choco Big Pack",
      "value": "Anthon Berg Opera Choco Big Pack (Post Edited)"
    }
  ]
}

Note

Important: For pre-translated content, your submitted value moves to intermediateValue when post editing starts. Upon completion, you'll have originalValue, intermediateValue (your original translation), and value (the post-edited text).

Best practices for post editing only

Provide context fields: Include relevant context fields (type: "context") to help post editors understand the content better
Use appropriate policies: Choose only-light-editing for quick improvements or only-full-editing for comprehensive post editing
Quality of input: The better your input translation quality, the more efficient the post editing process
Field types: Only localizable fields will be post edited; context and internal fields remain unchanged

Fields

Intermediate values

Machine translation will at times store translated content in the intermediateValue of a field. This intermediateValue will contain the machine-translated content and can be applied for various purposes, such as publishing content quickly before human localization is available.

Note

Note: In pre-translated workflows, intermediateValue holds your submitted translation during post editing. The final post-edited text is returned as value at completion.

States and error handling

Content requests with machine translation pass through the normal states of a request, but may have usable content before they reach a completed state.

If your intent is to use the partial content you should go through the fields and pick out the value you want to use. In most cases picking out value and falling back to intermediateValue when unavailable is a good strategy. If both value and intermediateValue are unavailable, it indicates that our system has not yet been able to perform the requested machine translation.

For pre-translated content requests, during post editing your submitted translation is available as intermediateValue. After completion, use value (the post-edited text).

Our system runs machine translations against the provider asynchronously, therefore, we recommend synchronizing your processes based on the last state change, as explained in our synchronization guide.

In most cases machine translations will complete in a few minutes, but if there is a large queue of requests or if there is a temporary failure with the machine translation provider this may be longer.

We currently retry machine translations for up to 48 hours before giving up. To avoid leaving content requests in a limbo our platform will cancel them at this point by moving their state to canceled.

Post editing requests typically complete within a few hours to a few days, depending on the volume and complexity of the content.

Related pages

Content API

Fields