Translation is complex and time consuming. There are many ways to handle it, and you’ll get the best results working with trained translators, but what if a perfect translation isn’t really necessary or cost effective for your needs? Machine translation can help you with this.

The true power of machine translation lies in its speed and cost. While it isn’t always 100% accurate, you get it instantly. Because it can be done so quickly, this opens the door to some interesting possibilities. For teams with translators onboard, machine translations can give them a starting point that is mostly accurate. Since they won’t be working from a blank slate, they will be more efficient. For those situations where machine translation is good enough for what you need, it is incredibly cost effective.

Automating Translation in Kontent

We can get the benefits of machine translation in Kontent and make it seamless for content editors. From their perspective, all they have to do is create their content, select which languages they want to translate into, and move the content item into a "Translation pending" workflow step. From there, they wait until the item is automatically moved into the "Translation review" step and then the translated content is ready for editing or publishing. I’ve built a demo of this using the Content Management API v2, a couple of webhooks triggered by workflow events, a custom element, and the Azure Translator Text API. 

Here’s how it works at a high level:

Trying It Out for Yourself

The source code for the translation connector is available in two repositories on GitHub: one for the custom element, and the other for the Azure functions to handle the webhooks. There’s more information about setup and development in the README files of those projects, but let’s go over the main steps for configuration.

This video put together by my colleague Ryan Overton gives you a good overview of what the rest of this post covers. 

Play video

Step 1: Configuring Your Languages

The first thing to do is make sure you’ve added one or more additional languages to your project. When setting the Codename for your languages, you must use language codes supported by Microsoft’s Translator API.

Step 2: Add Custom Element

The custom element needs to be present on all the content types we need to translate. The easiest way to do this is to first create a content snippet. The snippet will need only one element added, our custom element:

1. In Kentico Kontent, choose Content models from the app menu.
2. Change to the Content type snippets tab.
3. Click the Create new button.
4. Enter a name for the snippet (e.g. "Translation")
5. Add a Custom element.
   • Title – Translation settings
   • Hosted code URL – See below
   • Parameters - See below

Hosted code URL

For production use cases, you should fork the repository and deploy the custom element yourself. If you just want to do a quick test, you can use https://kontent-translation-connector-custom-element.netlify.com/. This is the deployed version of the master branch of the repository.

Parameters

The JSON parameters required for the component are detailed in the configuring the custom element section of the repository’s readme. The full JSON will look something like this:

{
    "debug": false,
    "cmApiKey": "<YOUR_API_KEY>",
    "pendingWorkflowStepId": "<YOUR_WORKFLOW_STEP_GUID>"
}

Finally, add the content type snippet to your content types.

Step 3: Configuring Workflow Steps

You will need to add two workflow steps to your project. They can be added anywhere in your flow. The Translation pending step is used to start the translation process. The Translation review workflow step is used to trigger the next language or finish the translation process and indicate that a language variant is ready for review.

Step 4: Get Azure Translator Text API Key

The next step will need an authentication key for the Translator Text API. You can get this by:

1. Logging into the Azure portal
2. Creating a new "Translator Text" resource
3. Opening the new resource
4. Going to "Keys" and copying one of the keys

In case you have any trouble, Microsoft provides a detailed how-to guide for signing up for the Azure Translator Text API and getting the authentication key.

Step 5: Deploy the Webhook Handlers Project

In order to be able to react to the workflow step changes, we’ll need to deploy the translation connector’s Azure function project. This project contains two serverless functions. Serverless functions are an effective and inexpensive way to host and run individual functions without needing to manage a whole project and the associated hosting infrastructure. The two functions in our project are designed to receive notification from Kontent that an item has changed into the workflow steps we are watching to perform the translation and update our content. In other words, these functions do our heavy lifting. 

This project is deployed like any other Azure function project. You can automate the deployment or manually deploy with the Azure Functions extension for VS Code. The local.settings.template.json file in the repository should be renamed to  local.settings.json and edited to reflect the values from your project. Details for the expected values are available in the repository’s readme under the Environment Variables section.

Step 6: Configure the Webhooks

Now that the webhook handlers are in place, you’ll need to configure two webhooks. These will tell Kontent what URLs we want to notify when items change workflow steps. The URLs of the deployed Azure functions need to be publicly accessible for Kontent to be able to send requests to them.

Translation pending webhook

The first webhook is for triggering the actual translation. The URL address for this webhook will point to the TranslationPendingHandler endpoint in this project. The URL will look like: https://<PUBLIC_BASE_DOMAIN>/api/TranslationPendingHandler.

You also need to configure only the Workflow steps of content items to watch trigger to a dedicated workflow step designed to trigger the translation connector. I recommend Translation pending as the name. The triggers should essentially look like this:

Translation complete webhook

The second webhook is for signaling that a translation has finished and to start the next translation. The URL address for this webhook will point to the TranslationReviewHandler endpoint in this project. The URL will look something like: https://<PUBLIC_BASE_DOMAIN>/api/TranslationReviewHandler.

You also need to configure only the Workflow steps of content items to watch trigger to a dedicated workflow step designed that indicates that a translation is complete and ready for review. I recommend Translation review as the name. The triggers should essentially look like this:

Step 7: Triggering the translation

As mentioned at the beginning, content editors now have the option to create content in English, the default language, and select which language variants to automatically populate using the custom element we added earlier. 

The final thing they have to do to trigger the translation is to change the default language variant of a content item into the Translation pending workflow step and wait. The webhook handlers will trigger and the code will update the selected language variants.

What’s Next?

In this example, you’ve learned how you can get a simple machine translation in your project. 

Using this sample as a baseline, you can extend or adjust this to enable other machine translation providers, or even integrate with a translation service that provides a human-based translation. You can get the code for both the Azure functions project and the custom element project on Github.

There’s a lot of other ways you can enhance your content with integrations. If you’re looking for some more examples or inspiration, check out our other available integrations.