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.

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

      

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

      
   5. 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.

   Add Custom Fields in XTM (Optional)

   Follow the steps below to add custom fields in XTM:

   1. Navigate to Configuration > Data > Custom fields.
   2. Under Project custom fields, click Add.
   3. In the Add custom field modal, enter the field name and select Text field in the Field type drop-down.

      Note: Ensure that the checkbox for the Active field is selected.

   4. Click Save.
   

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.

   Additional Resource: Learn more about Workflows.

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, click the Marketplace icon.
   3. Locate the XTM app from the list of apps and click the Install button.
   4. 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.

4. For configuring the app, refer to the Machine Translate section.
   1. 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.
   2. 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.

5. 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. To do this, 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 (details covered in the next section). 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.
      9. XTM Custom Fields (Optional):

         Select one or both of the following fields to send to the custom fields in XTM when creating the project:

         • Submitter’s Name
         • Contentstack Entry Link
         Note:

         • The field(s) (contentstack_entry_link, contentstack_initiator_name) must exist in the Custom fields section of the XTM app.
         • When you select Submitter's Name in the XTM Custom Fields, the submitter's name will appear in the Status section of the Sidebar.
         
   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 the flow 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 drop-down. 
         

         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 select the Enable Additional Settings option, 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.
         1. Exclude Languages: Select the language(s) from the dropdown that you want to remove from the Language drop-down in the sidebar.
         
   6. Once done, click Finish and then the Save button.
   7. Reset the configuration:
      1. If you want to reset the configuration with other values, click the Reset Configuration button. 
         
      2. A popup 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 drop-down. 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 Apps.
      2. Select the App for XTM. By default, you will be in the Translate tab.
      3. In the Translate tab, create a project as follows:
         1. Language: Click the Language option, select a language and a filter template from the respective dropdowns.

            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 and select a template from the dropdown.
         3. Due Date (optional): The due date selected in the Sidebar app will be displayed in the Delivery due date field of the General info section for the specified project in XTM.
         4. Description (optional): The description provided for the project in the Sidebar app will be displayed in the Description field of the General info section for the specified project in XTM.
         5. Manage Fields: Click the Manage Fields button. In the Manage Fields modal, all fields are selected by default. If fields are specified in the Exclusion or Inclusion settings in the configuration, the fields displayed in the Manage Fields modal will reflect those settings.
            Deselect the fields you want to exclude from the translation and click Save.
         6. Create Project: Click the Create Project button to complete project creation.

         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

      4. In the Status tab:

         The Status tab displays the status of the project you created.

         • Select Project: Use the dropdown to choose the project whose status you want to display.
         • Project Status: Displays the status of your project, and the date and time of update, along with the submitter’s name if you selected Submitter's Name in the XTM Custom Fields.
           Click the vertical ellipses and click Cancel Project to cancel your project from the XTM portal.

           Note: When you click Cancel Project, the project deactivates only in the XTM portal. The localized language remains as it is.

         • Language Status: Displays the status of the individual language you selected.
           Click the Cancel icon next to the language to cancel a particular language while translation is in progress or after completion.
         

   Note: You can view the translation status of up to 10 recent projects in the XTM dashboard.

   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 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.