Kentico provides a way to retrieve and submit translation data through REST. This service allows you to manage document translations using HTTP request methods. You can utilize the REST service in the code of your custom translation services to transfer data in and out of the system.
Use the following root URL to access the REST translation service:
Replace the ~ character with the domain name and virtual directory of your website, for example: http://localhost/KenticoCMS/rest/translate/
Enabling the REST translation service
To set up your website for handling translation operations via the REST service:
- Ensure that all REST prerequisites are fulfilled on the machine hosting your website.
- Configure your application's web.config according to the instructions in Configuring the REST service.
- The settings in Settings -> Integration -> REST do not affect the translation service. You can leave the general Kentico REST service disabled.
- In the Kentico administration interface, open the Settings application.
- Choose the Content -> Translation services category and select the Enable REST translation service check box.
- Click Save.
Retrieving translation data from the system
To retrieve document translation data, send an HTTP GET request to a URL in one of the following formats:
- ~/rest/translate/content/currentsite/<culture code>/document/<alias path>
- ~/rest/translate/content/site/<site code name>/<culture code>/document/<alias path>
Set the target language of the translation by adding the corresponding culture code into the targetlanguage URL parameter. The system automatically fills in the source language based on the language version of the specified document.
The request returns a response containing XLIFF data that you can use as the translation source. The REST service only supports retrieval of a single object per request.
You can also use the following boolean parameters in the URL:
- TranslateDocCoupledData (true by default)
If true, the returned translation source data includes the content of the document's coupled data fields (i.e. the fields of the specific document type). The service only exports fields that have the Translate field flag enabled in the document type's form definition.
- TranslateEditableItems (true by default)
If true, the translation data includes the content of the document's editable regions.
- TranslateWebpartProperties (false by default)
If true, the translation data includes the properties of web parts placed on the document. The service only exports the values of properties that have the Translate field flag enabled in the web part definition.
- TranslateAttachments (false by default)
If true, the translation data includes the document's file attachments. Attachment translation must also be allowed in the website's settings.
See also: Configuring content for translation
Submitting completed translations
To import a translation into the system, send a POST request to the root URL of the REST translation service:
Add the XLIFF content of the completed translation into the body of the request.
The root URL of the service is the only access point used for submitting translations. The system automatically identifies the target document based on the XLIFF data. When the system processes the request, it creates the appropriate language version of the document (if necessary) and inserts the translation data.
POST http://localhost/KenticoCMS/rest/translate/ User-Agent: REST client Authorization: Basic <enter <username>:<password> encoded in Base64> Host: localhost Content-Type: text/xml <xliff version="1.2"> <file original="cms.document;9" source-language="en-US" target-language="fr-FR" datatype="htmlbody"> <body> <trans-unit id="menuitemname"> <source><![CDATA[Company]]></source> <target><![CDATA[Entreprise]]></target> </trans-unit> <trans-unit id="documentname"> <source><![CDATA[Company]]></source> <target><![CDATA[Entreprise]]></target> </trans-unit> <trans-unit id="editable;we"> <source><![CDATA[<p>Source text.</p>]]></source> <target><![CDATA[<p>Translated text.</p>]]></target> </trans-unit> <trans-unit id="editable;wh"> <source><![CDATA[Company]]></source> <target><![CDATA[Entreprise]]></target> </trans-unit> </body> </file> </xliff>