XTM App Installation Guide

XTM is a cloud-based translation management application that offers language localization to simplify the process of content distribution across systems. It is a simple, robust, and cost-effective solution that helps to broaden your reach to multiple customers with multiple languages and colossal content.

Contentstack Marketplace allows you to easily integrate the XTM application and use it within your stack to create localized versions of your entries.

Prerequisites

• XTM account
• Contentstack account
• Access to the Contentstack Organization/Stack as the Owner/Admin.

Let's go through the steps required to install and configure the XTM app within Contentstack Marketplace.

Steps for Execution

1. Fetch the credentials from your XTM account
2. Define workflow in Contentstack

   Note: Skip this step if you want to create a project only using the Sidebar Widget.

3. Install the XTM application
4. Translate your Content

1. Fetch the credentials from your XTM account

   To configure the application, you need to create an account in XTM. To do so, follow the below steps:

   1. Go to https://xtm.cloud and create a new account based on your requirement.
   2. Fetch the XTM details such as baseURL, user identifier, customer ID, UserCompany, and password required to set up the app configuration page.

   You can fetch the user ID from the User list section under Users in the XTM dashboard as given below:

   

   You can fetch the customer ID from the Customer list section under Customers in the XTM dashboard as given below:

   
   3. If you want to create a project using the Sidebar Widget, create or fetch a workflow in the XTM dashboard under the Configuration section. You can use this workflow name in the XTM Workflow field on the app configuration page.
   

   Note: In the XTM dashboard, you must define the languages and create a template for the translation process. Make sure these languages are present in Contentstack as well.

2. Define Workflow in Contentstack

   To use the XTM application, you must define the Workflow to initiate the translation process.

   Firstly, you need to create a content type and an entry. To do so, follow the below steps:

   1. Log in to your Contentstack account.
   2. Click the + New Stack button and then click the Create New button.
      
   3. Go to your stack, click the Content Models icon on the left navigation panel, and click the + New Content Type button.
   4. Create a content type by entering relevant details as given below:
      
   5. On the left navigation panel, select Entries. On the Entries list page, click the + New Entry button, select the content type and click the Proceed button.
   6. Add content in your entry that you want to translate, and Save the entry.

      Note: If you already have a stack, skip the above steps.

   Follow the steps below to define the Workflow for your stack:

   1. Navigate to your stack and click the Settings icon on the left navigation panel.
      
   2. Under Settings, click Workflows. 
      
   3. Define the workflow stages.
      
   
   4. Once done, click Enable Workflow and click the Save button.

3. Install the XTM application

   Follow the steps to install the application in Contentstack.

   1. Log in to your Contentstack account.
   2. In the left navigation panel, you will find the icon for Marketplace. Click the icon to navigate to Marketplace. 
   
   3. Select XTM from the list of apps.
   4. On the right-hand side, click the Install App button.
   
   5. In the Authorization window, select the stack where you want to install the app, accept the Terms of Service and Privacy Policy, and then click the Authorize & Install button. 
      

   You have successfully installed the XTM app to your stack in Contentstack.

   6. For the Configuration settings, refer to the Machine Translate section.
   7. On the UI Locations tab, you can see the predefined app locations. You can use the toggle button corresponding to each UI location to enable or disable it based on your requirements.
   8. If the webhook is enabled for your app, you can view the webhook logs under the Webhook tab.

   Additional Resource: For more information on UI location and webhooks, please refer to the Installed Apps guide.

4. Translate your content

   XTM lets you translate your content in two different ways:

   1. Machine Translate
   2. Human Translate

   Machine Translate

   The machine translation process can translate multiple languages in just one go.

   On the XTM Configuration screen, enter the following details:

   1. XTM Fields

      You can fetch the below details from your XTM account.

      1. XTM Base URL: The URL of the application.
      2. XTM User Identifier: Unique identification given to a user.
      3. User Company Name: The company name of the user.
      4. XTM Customer ID: Unique customer ID given to users.
      5. XTM Password: Company credentials for integration.
      6. XTM Workflow: Enter the XTM Workflow name if you want to create a project from the Sidebar Widget by selecting the Language option.
      7. Select Translation Type: XTM provides two translation types.
         • Machine Translate: Machine Translate helps to translate your entry data automatically once you update the workflow. It helps to process and translate data quickly.
         • Human Translate: Human Translate lets the user on the XTM side manually translate the content. This process is slower than machine translation.

         Note: The default translation type is Machine Translate.

      8. XTM Templates: This field can help to define the languages in which you want to translate your content. Click Get XTM Template, and a dropdown menu with a list of templates will appear. 
      
   2. Click the Next button.
   3. Configure the Contentstack Fields settings:
      1. You can create a project using multiple Workflows. Mark the Workflow checkbox and then click the Add Workflow button to fill in the following fields:
         1. Workflow: Set of instructions used to define a plan for a process.
         2. Workflow Stage: Define the initial Workflow stage for your translation.
         3. Next Workflow Stage: After translation, the Workflow stage will be changed to the stage you have defined in this field.
         4. XTM Templates: Creates projects using the selected XTM Template for the particular workflow.
         
      2. To create a project using the Sidebar Widget, check the From Sidebar checkbox and select a role from the Select Roles dropdown. 
         

      Note: The selected roles have access to 'Create Project' from the Sidebar Widget. By default, only the stack owner and admin have access to create project(s) from the Sidebar Widget.

      3. To publish an entry automatically to the specified environments after the translation, mark the Publish Entry checkbox and select the required environment(s) and the content type(s) to which you want to publish.
         
      4. Enable Additional Settings: If you enable Additional Settings, you can define the scope of your fields for translation. 
      
   4. Click the Next button.
   5. Configure the Additional Settings:
      1. Exclusions:
         1. Content Type Field Mapper: Define the fields of a particular content type you want to exclude from the translation.
         2. Field(s) to Exclude from All Content Types: Define specific fields of all the content types you want to exclude from the translation.

         Note: When the target language is not localized, the XTM app uses the source language code for exclusions. When the target language is localized, it will consider the target language code for exclusions.

         
      2. Inclusions:
         1. Content Type Field Mapper: Define the fields of a particular content type you want to include in the translation.
         
      3. Language Configuration: Define the content translation languages for XTM and Contentstack to avoid any mismatch between the language codes. All the entries from XTM languages will be localized into Contentstack languages. For any target languages not selected, the app uses the default language code of the stack. Click the Add Language button to add a language.
      
   6. Once done, click the Finish button.
   7. Click the Save button.
   8. To reset the configuration:
      1. If you want to reset the configuration with other values, click the Reset Configuration button. 
         
      2. A pop-up will appear. Click the Reset Config button to reset the entire configuration.
         

   Initiate the translation process

   Once you define the configuration for your XTM application, initiate the translation process by following the below steps:

   1. Navigate to the Entry page that you created in Step 2.
   2. Enter the content in the entry field.
   3. Click the Save button.

   Note: If you want to use the JSON Rich Text Editor field, you can select the XTM pre-configured JSON RTE template option from the Filter Template dropdown. To configure the Filter Templates in your XTM account, please contact XTM support.

   4. If you set the configuration to create a project using Workflows, follow the steps given below:
      1. In the right navigation panel, click Workflow Details.
         

      Note: Set Stage in the Workflow Details when you set Workflow for the first time.

      2. Click Change. To start the translation process, you need to change the Workflow stage, as defined in the XTM configuration page.
         
      3. Select the Workflow stage from the dropdown and click the Update button.
      
   5. If you set the configuration to create a project using the Sidebar Widget, follow the steps given below.
      1. In the right navigation panel, click Widgets.
      2. Select the option for XTM from the Sidebar Widget. By default, All Project Status will be displayed in the Sidebar.
      3. You can create a project by the following methods:
         1. Language: Click the Language option, select a language from the dropdown below, and click the Create Project button.

            Note: If you are using the JSON Rich Text Editor field, select the JSON RTE Filter template option in your XTM account.

            
            
         2. Template: Click the Template option, select a template from the dropdown, and click the Create Project button.
         

         Note: In the XTM Dashboard, the project name will be created in the following format: (content_type_uid-entry_title-entry_uid)
         Example: xtm-Human Translate-blta32a84cf37a0cc64

         If your role(s) is not configured to create a project using the Sidebar Widget, you will see only the All Project Status in the Sidebar, as below:

         

   Note: In the Sidebar Widget, you can check the translation status of the latest 10 projects created in the XTM dashboard in the All Project Status section based on the creation date. Contentstack Sidebar Widget provides insight about the XTM dashboard, such as the list of projects, the status of the translation (whether Completed/In-Progress), and the list of languages the content is translated.
   

   

   Human Translate

   In the Human translation process, an individual user manually translates the content. This process is slower than machine translation.

   On the XTM Configuration screen, enter the following details for human translation:

   1. XTM Fields
      • Select Translation Type
        • Human Translate

   Note: The rest of the configuration will be similar to the machine translation process.

   The process for human translation will be as follows:

   1. Navigate to the entry page. Click on the Widget icon in the right navigation panel.
   2. Within Widgets, click the Entry Widgets dropdown, and under Apps, select XTM App.
   3. Select the project ID from the dropdown. You need to select the ProjectID from the All Project Status section of the Sidebar Widget.

      Note: Project ID is a unique identifier given to the entry which needs to be translated. With the help of project ID, users can easily search for the entry in the XTM dashboard and translate the content manually.

   4. Navigate to the XTM dashboard to view the list of all the projects.
   5. Select the project based on your project ID. 
      
   6. In the left navigation panel, click Workflow. Assign different languages to different users so they can manually translate the content.
      
   7. Click the Start button.

      Note: Users need to log in via individual credentials in the XTM dashboard. Credentials are different for human and machine translation in XTM.

   8. Select the project based on project ID. Translate the content manually.
   9. Click the Finish button.
      

   You will be able to see the translated content in Contentstack.