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.

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

Currenly 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 vailable 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-automatic machine translation for the content request:

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

Activating post-editing machine translation for the content request:

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

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.

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 is unavailable it indicates that our system has not yet been able to perform the requested machine translation.

Therefore, we recommend synchronizing your processes based on the last state change, as explained in our

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.

Related pages

Content API

Fields