Translations¶
Note
This is only available on Plone 5.
Since Plone 5 the product plone.app.multilingual is included in the base Plone installation although it is not enabled by default.
Multilingualism in Plone not only allows the managers of the site to configure the site interface texts to be in one language or another (such as the configuration menus, error messages, information messages or other static text) but also to configure Plone to handle multilingual content. To achieve that it provides the user interface for managing content translations.
You can get additional information about the multilingual capabilities of Plone in the documentation.
In connection with that capabilities, plone.restapi provides a @translations endpoint to handle the translation information of the content objects.
Once we have installed plone.app.multilingual and enabled more than one language we can link two content-items of different languages to be the translation of each other issuing a POST query to the @translations endpoint including the id of the content which should be linked to. The id of the content must be a full URL of the content object:
POST /plone/en/test-document/@translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"id": "http://localhost:55001/plone/es/test-document"
}
curl -i -X POST http://nohost/plone/en/test-document/@translations -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"id": "http://localhost:55001/plone/es/test-document"}' --user admin:secret
echo '{
"id": "http://localhost:55001/plone/es/test-document"
}' | http POST http://nohost/plone/en/test-document/@translations Accept:application/json Content-Type:application/json -a admin:secret
requests.post('http://nohost/plone/en/test-document/@translations', headers={
'Accept': 'application/json',
'Content-Type': 'application/json',
}, json={
'id': 'http://localhost:55001/plone/es/test-document',
}, auth=('admin', 'secret'))
Note
“id” is a required field and needs to point to an existing content on the site.
The API will return a 201 Created response if the linking was successful.
HTTP/1.1 201 Created
Content-Type: application/json
Location: http://localhost:55001/plone/en/test-document
{}
After linking the contents we can get the list of the translations of that
content item by issuing a GET
request on the @translations endpoint of
that content item.:
GET /plone/en/test-document/@translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i http://nohost/plone/en/test-document/@translations -H 'Accept: application/json' --user admin:secret
http http://nohost/plone/en/test-document/@translations Accept:application/json -a admin:secret
requests.get('http://nohost/plone/en/test-document/@translations', headers={
'Accept': 'application/json',
}, auth=('admin', 'secret'))
HTTP/1.1 200 OK
Content-Type: application/json
{
"@id": "http://localhost:55001/plone/en/test-document/@translations",
"items": [
{
"@id": "http://localhost:55001/plone/es/test-document",
"language": "es"
}
]
}
To unlink the content, issue a DELETE
request on the @translations
endpoint of the content item and provide the language code you want to unlink.:
DELETE /plone/en/test-document/@translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"language": "es"
}
curl -i -X DELETE http://nohost/plone/en/test-document/@translations -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"language": "es"}' --user admin:secret
echo '{
"language": "es"
}' | http DELETE http://nohost/plone/en/test-document/@translations Accept:application/json Content-Type:application/json -a admin:secret
requests.delete('http://nohost/plone/en/test-document/@translations', headers={
'Accept': 'application/json',
'Content-Type': 'application/json',
}, json={
'language': 'es',
}, auth=('admin', 'secret'))
Note
“language” is a required field.
HTTP/1.1 204 No Content
Expansion¶
This endpoint can be used with the Expansion mechanism which allows to get additional information about a content item in one query, avoiding unnecesary requests.
If a simple GET
request is done on the content item, a new entry will be shown on the @components
entry with the URL of the @translations endpoint: