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.
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
.