Set up a Translation System with Contentstack Webhooks and Workflows, AWS Lambda, and AWS Translate

While Contentstack does not offer translation services, it offers easy integration with third-party translation providers. In this guide, we will learn how to set up a translation system using Contentstack's webhook and workflows along with AWS Lambda and AWS Translate.

Additional Resource: You can also set up a translation system using Memsource, read our guide on how to Set up Translation System with Contentstack Webhooks, Memsource, and AWS Lambda.

Here's a quick overview of the process: When the workflow stage of entry in the master locale changes to “Send to Translation,” a webhook is triggered, which invokes an AWS Lambda code. This code translates content using AWS Translate and then localizes the entry with the translated content using a Content Management API request. This also changes the workflow stage status of the entry to “Review Translation.”

Here are the steps to set up this translation solution:

1. Set up the essentials
2. Set up workflows for translation
3. Set up Lambda function for translation
4. Trigger a webhook to initiate translation

Prerequisites

• Working knowledge of AWS API Gateways
• Access to the AWS environments such as AWS Lambda, AWS API Gateway, and AWS IAM
  
• AWS Secret Key, ID, and region
  
• Contentstack account
  

1. Set up the Essentials

   First, create a stack, and add a content type (in our example it is Product), add entries to it, at least one additional language, and a publishing environment.
   
   Once you have these configured, then you're ready to begin the integration process for translation.
   
   For this exercise we have created a content type with the following structure:
   
   

2. Set up Workflows for Translation

   To set up workflows for the translation process within Contentstack, follow the below steps:

   1. Create a workflow by hovering over the “settings” gear icon and clicking on Workflows.
   2. Click on Add Workflow.
   3. Add stages, as shown in the following screenshot:
      
      
   Once the editor changes the workflow stage to “Send to Translation,” the webhook will be triggered and call the AWS Lambda function.
   
   For this exercise, we have created a workflow with the following stages:
   
   
   
   Now go to the Workflow Settings page and note down the WORKFLOW ID that we just created as shown below (we will need this ID later when we make Postman call to retrieve the ID of the Review stage):
   
   
   
   We will need the UID of the Review stage. To get the UID of the “Review” stage, open Postman or any other API collaboration & development platform and make a GET request on the following URL, enter the Workflow ID at the end of the URL:
   
   https://api.contentstack.io/v3/workflows/{YOUR WORKFLOW UID}
   
   You will get the following response:
   
   
   
   This UID is used while setting up the webhook in Contentstack as a custom header. So make a note of it.
   
   

3. Set up Lambda Function for Translation

   Perform the following steps to set up your AWS Lambda function:

   1. Login to your AWS Management Console, select AWS Lambda Service from the service list.
   2. Click on the Create Function button, and then the Author from Scratch option.
   3. Configure the lambda based on your requirements. Choose Node.js as your run-time language.
      
      

      Note: You can use any language instead of Node.js. You can also add triggers to your lambda to push an event to SNS when the lambda is invoked.

   4. AWS Lambda offers an inline code editor. You can write your lambda code here or alternatively upload the code. For our example, we will have created the sample which you can get by contacting our Support team.
      
      
   5. In the Environment variables section, enter the credentials against the variables as follows:
      
      
      
      
      
   6. In the Lambda function handler and role, keep index.handler as Handler and for the Role choose an existing role or create a new role from template(s).
   7. Review your setting and click on the Create Function option if everything you entered is correct.
   8. Next, you need to create a trigger for your lambda function. Scroll up to the Designer section and click on + Add trigger.
   9. On the Add trigger screen, from the Select a trigger dropdown, select API Gateway.
   10. From the API dropdown, select Create an API. 
   11. Then, select REST API inside the API type block, select Open from the Security dropdown, and click on Add.
   12. An API for your lambda function is now created. Under the Design block, click on API Gateway, you will see the Details link. Click on it and you will find your API endpoint. Make a note of it as we will need it while setting up our webhook in Contentstack.
       
       

   Once you do this setup, AWS Lambda will run the code that we have uploaded and translate the English content into French and will deliver the translated content to your content type. The workflow stage of the translated entry also changes to Ready for Review.

4. Trigger a Webhook to Initiate Translation

   We will now set up a webhook that triggers when the entry workflow stage is set to Send to Translation. To do this, log in to your Contentstack account and perform the following steps:

   1. Hover over the “settings” gear icon and click on Webhooks
   2. Click on + New Webhook
   3. Enter any valid name for your webhook, for example, AWS Lambda For Translation.
   4. In the URL to notify field, enter the AWS Lambda URL, where the webhook will notify about the change.
   5. Inside Custom headers, provide the details as shown below:
      
      
      
      

      Note: The role and role_name headers are optional. That is, they are required only when you are assigning the translation to be reviewed by any member of the stack. Only “workflow_stage_uid” is mandatory which we got through Postman.
      

   6. Under the When section, select the options Any > Entry > All > Workflow Stage Changed > (Workflow name) > (Stage name for example, "Send to Translation").
   

This will configure your webhook to trigger on a workflow stage change such as “Send to Translation,” like in the above workflow example. As soon as the webhook is triggered, it notifies the specified URL about the event along with a JSON payload.

Additional Resource: Though we don't provide translation, we do provide the ability to integrate with third-party translation providers that will translate content for you. All you need to do is make use of Contentstack workflows and set up a webhook trigger to initiate the translation process. Use any popular translation tool, such as Worldserver and iLangl, to translate your content. Here's our Manage Content Translation in Contentstack guide that gives a detailed explanation of how you can do all of this.