Related pages

HTTP API

Machine translation

Experimental

This feature is currently experimental. The things explained here may change before this feature is fully stable. Contact us if this documentation is inadequate or if you wish to see changes to the features described here.

Using machine translation over our HTTP API involves adding hints to either fields or to 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 for a certain field. Hints may also be placed on the entire request in which case it will apply to all fields in the request.

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

Argument Description
policy Optional policy to use. If this hint is placed on a field the policy will apply to the field. For entries this applies to all fields that do not specify a policy.
provider Optional provider to use. If this hint is placed on a field the provider will be used for the field. For entries this will apply to all fields that do not specify a specific provider.

Policies

To activate machine translation a policy must be set either on a field or using a default value on the content request. 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.

Providers

Providers can be specified using the provider argument. Currently only a single provider is supported:

Provider Description
google-translate Use Google Translate for the machine translation.

Examples

only-automatic policy, no preference for a provider:

{
  "type": "machine-translation",
  "policy": "only-automatic"
}

with-post-editing policy, no preference for a provider:

{
  "type": "machine-translation",
  "policy": "with-post-editing"
}

only-automatic policy, request the use of google-translate:

{
  "type": "machine-translation",
  "policy": "only-automatic",
  "provider": "google-translate"
}

Use default policy, request the use of google-translate:

{
  "type": "machine-translation",
  "provider": "google-translate"
}

Placing on a field:

{
  ...
  "fields": [
    {
      "id": "short description",
      "type": "localizable",
      "value": "Coffee Brewer with integrated timer & automatic shut down.",
      "hints": [
        {
          "type": "machine-translation",
          "policy": "only-automatic"
        }
      ]
    }
  ],
  ...
}

Setting defaults for fields in a content request:

{
  ...,
  "hints": [
    {
      "type": "machine-translation",
      "provider": "google-translate"
    }
  ],
  "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.

Attributions

Attributions are used to flag what attributions must be displayed for values in a field. These attributions can either be connected with value or intermediateValue and is stored in attributions and intermediateAttributions.

Within the arrays are objects that in their simplest form contain a key type which indicates what type of attribution is required:

Type Description
google-translate Attributions related to Google Translate must be displayed. Your system must omply with the HTML Markup Requirements found at https://cloud.google.com/translate/markup and the attribution requirements found at https://cloud.google.com/translate/attribution.

Example of an attribution:

{
  "type": "google-translate"
}

Examples

Example of a field with an intermediateValue:

{
  "id": "product-listing-text",
  "type": "localizable",
  "data": "html",
  "originalValue": "Coffee Brewer with integrated timer & automatic shut down.",
  "intermediateValue": "Kaffebryggare med integrerad timer & automatisk avstängning.",
  "intermediateAttributions": [
    {
      "type": "google-translate"
    }
  ]
}

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.