Translating content via REST

✖
Copy to clipboard

Kentico EMS required

Features described on this page require the Kentico EMS license.

Kentico provides a way to retrieve and submit translation data through REST. This service allows you to manage page 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:

~/rest/translate/

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:

  1. Ensure that all REST prerequisites are fulfilled on the machine hosting your website.
  2. 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.
  3. In the Kentico administration interface, open the Settings application.
  4. Choose the Content -> Translation services category and select the Enable REST translation service check box.
  5. Click Save.

Retrieving translation data from the system

To retrieve page 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 page.

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.

Examples:

~/rest/translate/content/site/CorporateSite/en-us/document/Services?targetlanguage=fr-fr
~/rest/translate/content/currentsite/fr-fr/document/Company/Careers?targetlanguage=cs-cz

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 page’s coupled data fields (i.e. the fields of the specific page type). The service only exports fields that have the Translate field flag enabled in the page type’s form definition.
  • TranslateEditableItems (true by default)
    If true, the translation data includes the content of the page’s editable regions.
  • TranslateWebpartProperties (false by default)
    If true, the translation data includes the properties of web parts placed on the page. 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 grouped attachments, unsorted attachments, and the content of the page’s File fields. The attachment image variants are not included. 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:

~/rest/translate/

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 page based on the XLIFF data. When the system processes the request, it creates the appropriate language version of the page (if necessary) and inserts the translation data.

Sample POST request 



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="pagename">
        <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>