A Strong Performer in The Forrester Wave™: Digital Experience Platforms, Q4 2025
CS-log-dark.svg

Setting up a Translation System Using Contentstack Webhooks, AWS Lambda, and XTM

XTM is a cloud-based content translation management solution that helps organizations to streamline complex localization processes and maximize translation reuse. Its scalable and flexible architecture allows it to integrate with apps such as Contentstack seamlessly.

In this guide, we will go through the steps required to set up a language translation system for your Contentstack-powered website by using Contentstack Webhooks, AWS Lambda, and XTM.

Process Overview: We will first set up the essentials, such as creating a stack and one additional language, in Contentstack. We will create a workflow and 4 stages to it. We'll set up a lambda function that will help us create the bridge between Contenstack and XTM for translation.

We will also set up a webhook such that when the workflow stage in an entry changes (let's say from Draft to Send for Translation), the webhook will issue a trigger to our lambda function to initiate the translation process with XTM. It will then translate the content of the entry in the required language along with changing its workflow stage to “Completed.”

Prerequisites

Note For this example, we assume that you already have a Project Manager account in XTM that will help you create projects in XTM. If not, please sign up and get your account created. You will receive all the details required to log in to XTM such as URL, username, password, and so on.

Steps for Execution

Here are the steps required to set up this translation system:

  1. Set up the essentials in Contentstack
  2. Set up the workflow for translation in Contentstack
  3. Configure your project in XTM
  4. Set up the AWS lambda function for translation
  5. Trigger a webhook to initiate translation
  6. Try out the steps

Let's get started!

  1. Set up the Essentials in Contentstack

    To set up the essentials, log in to your Contentstack account and follow the steps given below:

    1. Create a stack, add a content type (for our exercise, we have created a Single Content Type named XTM).

      In our example, we have used “title,” “url,” “single_line (named Heading),” and “rich_text_editor (named Body)” fields. We will translate the content of these fields. Content of special fields such as File, Boolean, Reference, Select will not be translated.
      Click to enlarge


    2. Create a management token for your stack which we will use later while setting up the lambda function. 
    3. Next, create languages (locales) in your content type (XTM). In our example, we have added two languages:

      English [en-us] which is the source language
      Chinese [zh] is another language which will be our target language

    With these steps, we have set up the essentials in Contentstack. Let's now move ahead with creating a workflow.

  2. Set up Workflow for Translation in Contentstack

    To set up workflows for the translation process, perform the following steps:

    1. Hover over the Settings gear icon and click on Workflows.
      Click to enlarge




    2. On the Workflow Settings page, click on + ADD WORKFLOW.
      Click to enlarge




    3. Provide a suitable name to your workflow and an optional description.
    4. Under the Scope option, select if this workflow should be applied to All Content Types or to a Specific Content Type(s). For our example, we will select the Specific Content Types(s) option, select our content type, XTM, and then click on Add as shown below:
      Click to enlarge




    5. Inside the WORKFLOW STAGES option, add 4 stages (for example, Draft, Send for Translation, Review, and Completed) as shown below:

      Click to enlarge

      Additional resource: To learn more about workflow and its stages, refer to the set up workflows guide.

    6. Lastly, click on the Enable Workflow checkbox and then on the Save button.

    With these steps, our workflow is ready. When the editor changes the workflow stage from “Draft” to “Send for Translation,” the webhook will be triggered and call the lambda function (we will set these up later in the guide).

    Now go back to the Workflow Settings page and note down the WORKFLOW ID as shown below (we will need this ID later when we setup our lambda function):

    Click to enlarge

    With these steps, we have created our workflow. Let's now move ahead and set up a project in XTM.

  3. Set up and Configure Your Project in XTM

    For this exercise, you need a project manager (or an admin) account with XTM so that you can create projects in the XTM app. You can sign up with one of their plans and get started with setting up your account.

    Activate Machine Translation in XTM

    Assuming that you have a project manager account in XTM and have logged in to the app, the first thing you need to do is to activate machine translation in XTM. To do this, follow the steps given below:

    1. Once you log in to the XTM app, you will be on the Projects page. Click on the Settings gear icon as shown below:

      Click to enlarge


    2. On the page that opens, click on the Settings option.
    3. From the left navigation panel, click on Translation as shown below:

      Click to enlarge


    4. Then, select the Machine translation option from the menu and select your preferred MT engines. For our example, we have used Amazon Translate as shown below:

      Click to enlarge

      Note You can select the MT engine you like but ensure you have the necessary keys for using that engine. You will need to enter those keys in the next step.

    5. Leave the default values under the General options section untouched.
    6. Scroll down to the Amazon Translate section (because we selected AWS Translate, if you select others in the above step such as Google Translate, this section will change to Google Translate and you need to provide the necessary details here specific to Google Translate), and keep the Default setting option checked.
    7. Provide AWS access key ID, AWS secret access key, and click on Synchronize. You will get a message when it synchronizes successfully as shown below:

      Click to enlarge

    8. Save your settings by clicking on Save.

    We have now activated the machine translation. Let's now go ahead and create a project in XTM. 

    Create a Project in XTM

    Follow the steps given below to create a project in XTM:

    1. Click on the Projects link at the top and then Add project as shown below:

      Click to enlarge


    2. On the page that opens, under the General information section, enter the Customer name and Project name. You can leave the remaining options blank.
    3. Under the Translation section, provide the Source language (English USA in our example) and Target languages [Chinese (simplified) in our example]. You can add more languages if you like and leave the other options unchanged.
    4. You can leave the options under the Workflow, Settings, and Machine translation sections to their default values as shown below:

      Click to enlarge

      Note Ensure the Use Amazon machine translation option is checked (if not already checked by default) to let XTM use the AWS MT engine.

    5. Lastly, click on the Create button to create the project.
    6. Once the project is created, it will be available on the Projects page. Click on the blue "i" symbol at the right and note down the project ID. We will need it when we create our lambda function:

      Click to enlarge


    The XTM project is now created. Let's move ahead and set up a lambda function.

  4. Set up the AWS Lambda Function

    The lambda function (once invoked) will take the content of the entry and get it translated from XTM. After that, it will place the translated content in the entry inside the Chinese locale and update the entry workflow state to Completed.

    Let's now create the lambda function by using the steps given below:

    1. Log in to your AWS Management Console, select Lambda from the Services list.
    2. Click on the Create function button, and then the Author from Scratch option.
    3. Provide a name to your lambda function inside the Function name field, select Node.js 14.x as your Runtime language, and click on the Create function button.
    4. You will get a success message on creation of the lambda function. Contact our Support team to get the sample code.
    5. Once you receive the code, upload it as a ZIP file by selecting .zip file from the Upload from drop-down menu inside the Code source section.
    6. Keep Handler as index.handler (under the Runtime settings section)& and click on Save.
    7. Scroll up and click on the Configuration tab. By default, the Environment variables option will be selected. Click on Edit and then Add environment variable:

      Click to enlarge


      api_key: <<Stack API Key>>
      base_url      : https://api.contentstack.io/v3/ (if EU, then https://eu-api.contentstack.com/v3/)
      contentTypeUid: <<UID of the content type, in our example it is xtm>>
      management_token: <<Stack Management Token>>
      projectId: <<XTM Project ID we generated above>>
      sourceLocale: <<Source language>>
      sourceTarget: <<Target locale of the entry in Contentstack, in our case it is Chinese (zh)>>
      targetLocale: <<Target language>>
      userCompanyName: <<XTM User company that you created while setting up the account>>
      userIdentifier: <<User identifier key of XTM account>>
      workflowUid: <<UID of the workflow that you created above>>
      xtmBaseUrl: https://api-test.xtm-intl.com/project-manager-api-rest/
      xtmPassword: <<Your XTM account password>> 

    8. After adding these details, click on the Save button.
    9. Staying inside the Configuration tab, click on General configuration and increase the timeout value to 1 minute by clicking on the Edit button.
    10. Your lambda function is now ready. Let's add a trigger (API Gateway) for this lambda function. To do this, scroll up to the Function overview section and click on + Add trigger.
    11. On the Add trigger screen, from the Select a trigger dropdown, select API Gateway.
    12. From the API dropdown, select Create an API. Then, select REST API inside the API type block, select Open from the Security dropdown, and click on Add.

      Click to enlarge


    13. An API for your lambda function is now created. Under the Configuration tab, the Triggers option will be selected by default. Click on the Details link and you will find your API endpoint. Make a note of it as we will need it while setting up our webhook in Contentstack.

      Click to enlarge


    We are now ready with our lambda function, let's move ahead and set up the webhook that will invoke the lambda function once the workflow stage changes to Send for Translation.

  5. Trigger a Webhook to Initiate Translation

    To create and set up a webhook in Contentstack, log in to your Contentstack account (if you have logged out) and perform the following steps:

    1. Hover over the Settings gear icon and click on Webhooks.
    2. On the Webhooks page, click on + New Webhook.
    3. On the Create Webhook page, fill up the Name field (for example, XTM Translation).
    4. In the URL to notify field, enter the URL (the API endpoint of the lambda function) that you generated in the previous step.
    5. Scroll down to the When section for creating a trigger for the webhook as shown below:
      Click to enlarge



    6. Ensure to check the Enable Webhook option and click on the Save button to save your settings.

    With these steps, we have completed the entire set up and now we are ready to try it out.

  6. Try out the Steps

    We are now ready to test the setup.

    1. Create an entry inside the content type. After you have added the details in the fields, change the workflow stage by selecting Send for Translation from the WORKFLOW DETAILS section on the right side.
    2. This will trigger the webhook and it will invoke the lambda function.

    3. Now select Chinese from the locale drop-down and you should see your entry translated in the target language, Chinese and the workflow stage changed to Review.