HTTP API

Machine translation

Using machine translation over our HTTP API involves adding hints the main content request. These hints are used to activate machine translation and to automatically fulfill certain requests and to partially fulfill others.

Hints

A hint of the type machine-translation is used to activate machine translation.

The machine-translation hint can only be used for localizable fields.

Argument	Description
`policy`	Which policy to use.

Policies

To activate machine translation a policy must be set. Available policies 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-automatic`	Request only automatic translation. The incoming `value` of fields will be machine translated and be made available as `value`.
`with-full-rewrite`	Deliver a machine translation quickly and then deliver a human localization later. The machine translated value will be made available on the field as `intermediateValue` and `value` will not be present until human localization is done.
`with-post-editing`	Request that something is machine translated and post-edited by a human. The machine translated value will be made available on the field as `intermediateValue` and `value` will not be present until post-editing is completed.

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 things in the intermediateValue of a field. This value will be the machine translated content and can be used for things such as going live with the content early while waiting for a human localization.

Providers

The machine translation hint in a response will contain the provider property. This property describe whith machine translation provider was used. If intermediateValue of a with-full-rewrite or with-post-editing, or value of a only-automatic request is used, it is required to give attributions to this provider anywhere the content is used in your systems.

If value of with-full-rewrite or with-post-editing is used, this is not required.

Provider	Description
`dynamic-routing`	MT provider dynamically chosen by Contentor. Contant us as dev@contentor.com for more information regarding attributions.

Example:

"hints": [
    {
        "type": "machine-translation",
        "policy": "only-automatic",
        "provider": "dynamic-routing"
    }
]

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 platform has not yet been able to perform the requested machine translation.

Our platform runs machine translations against the provider asynchronously, so synchronizing based on last state change is recommended.

Note

We want feedback on how to best handle errors for you. If you have any input about our current error handling or ideas for the future please send us an e-mail at dev@contentor.se.

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