Changelog

XTM App Installation Guide

XTM is a powerful cloud-based translation management platform designed to streamline language localization and content distribution across multiple systems. With its robust, user-friendly, and cost-effective features, XTM enables businesses to efficiently manage translations, ensuring consistent multilingual experiences at scale.

Through the Contentstack Marketplace, you can seamlessly integrate the XTM app into your stack to create and manage localized versions of your content with ease.

Prerequisites

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

Follow this step-by-step guide to install and configure the XTM app within your stack.

Steps for Execution

Retrieve your Credentials from XTM
Create Workflow in Contentstack
Install and Configure the XTM app in Marketplace
Use the XTM App for Machine Translation
Use the XTM app for Human Translation

Retrieve your Credentials from XTM
To configure and connect the XTM app within Contentstack, you need to fetch the credentials from your XTM account by following the given steps:
1. Log in to your XTM Cloud account and copy the Base URL, Company name, and Password. During the app configuration in step 3, paste these values into the corresponding fields: XTM Base URL, User Company Name, and XTM Password.
2. To get the User ID, navigate to Users > User list, select the relevant user, and click the “Info” icon. Copy the ID and paste it into the XTM User Identifier field in step 3.
3. To get the Customer ID, navigate to Customers > Customer list, select the relevant customer and click the “Info” icon. Copy the ID and paste it into the XTM Customer ID field in step 3.
4. If you want to create projects in Contentstack using the Entry Sidebar or Full Page app, you must create a workflow in XTM.
  To do this, navigate to Configuration > Settings > Workflow. Under Workflow definitions, create a new workflow by clicking the Add button or select an existing one. Copy the Workflow definition name and paste it into the XTM Workflow field in step 3.
Note: In XTM, you must define the languages and create a translation template to enable the translation process. Ensure that the languages configured in XTM also exist in your Contentstack to maintain seamless integration.
Add Custom Fields in XTM
Mapping custom fields from Contentstack into XTM adds valuable context and traceability to your localization process. For instance, adding Submitter’s Name, Contentstack Entry Link, Contentstack Stack API custom fields during app configuration in step 3.
To add custom fields in XTM, follow the given steps:
1. Navigate to Configuration > Data > Custom fields. Under Project custom fields, click the Add button.
2. In the Add custom field modal, enter the Field name, select Field type as Text field from the dropdown, and click Save.
  Note: Ensure that the checkbox for the Active field is selected.
Create Workflow in Contentstack
Before using the XTM app for translations, you must define a Workflow to create a project and initiate the translation process.
To create a workflow, log in to your Contentstack account, and follow the steps:
1. Navigate to your stack, click Settings in the top navigation panel, and then click Workflows. Click the + New Workflow button to add a new workflow.
2. On the workflow creation page, enter the following details:
  1. Provide the Workflow Name and Description.
  2. Set the Scope of the workflow that includes setting up the branches and content types.
  3. Define the Workflow Stages.
  4. Select the Workflow superuser(s) from the provided dropdown. To activate the workflow, click the Enable Workflow toggle button.
3. After filling up the details, click Save. A workflow is created to configure in the XTM app in step 3.
Additional Resource: To learn more, refer to the Workflows documentation.
Install and Configure the XTM app in Marketplace
To install the app in Contentstack, log in to your Contentstack account and follow the steps below:
1. Navigate to the “App Switcher” icon in the top-right corner and click Marketplace.
2. Click Apps from the left panel.
3. Within the Marketplace, locate the XTM app and click Install.
4. In the pop-up window, select the stack where you want to install the XTM app, accept the Terms of Service, and click the Authorize & Install button.
5. On the Configuration screen, enter the following details:
  1. XTM Fields: Enter your XTM credentials to connect Contentstack with your XTM account.
    1. Provide the XTM Base URL, XTM User Identifier, User Company Name, XTM Customer ID, XTM Password, and XTM Workflow retrieved in step 1.
    2. XTM offers two types of translation methods. Under Select Translation Type, choose one:
      - Machine Translate: Machine Translation automatically translates your entry content as soon as you update the workflow, enabling faster processing and translation of data. This option is ideal for quick turnarounds or when human review is not required.
        Machine Translate is, by default, selected.
        Additional Resource: Refer to the Use the XTM App for Machine Translation section for further steps.
      - Human Translate: Human Translation allows translators on the XTM side to manually translate the content. While this method takes longer than machine translation, it provides greater accuracy and quality control.
        Additional Resource: Refer to the Use the XTM App for Human Translation section for further steps.
    3. XTM Templates help you define the languages into which you want to translate your content. Click the Get XTM Template button; a dropdown menu appears with a list of available templates from XTM. Select the appropriate template that matches your localization needs.
    4. By selecting the XTM Custom Fields (Submitter’s Name, Contentstack Entry Link, or Contentstack Stack API), you can map additional metadata from Contentstack to XTM. These fields are sent to XTM when creating a translation project.
      Note:
      The fields contentstack_initiator_name, contentstack_entry_link, and contenstack_stack_api must exist in the Custom fields section of the XTM app. For more details, refer to the Add Custom Fields in XTM section.
      If you select Submitter’s Name, it will appear in the Status section of the Contentstack Entry Sidebar.
    5. Enable the Auto Assign Template toggle button to automatically select a translation template when initiating translations from the Entry Sidebar.
  2. Click the Next button.
  3. Contentstack Fields: Configure workflows, stages, and roles for project creation and translation within Contentstack.
    1. You can create a project using multiple workflows within Contentstack to define how content moves through the translation process. Mark the Workflow checkbox and then click the Add Workflow button.
    2. Select the Workflow from the dropdown and then fill up the four workflow stages: Request Stage, Completed Stage, In Progress Stage (optional), and Error Stage (optional) from the respective dropdowns.
    3. Select an XTM Template to create projects associated with the chosen workflow.
    4. Enable the Enable Workflow for Sidebar or Bulk Translate toggle button to apply your workflow configurations when sending entries for translation via the Sidebar or Bulk Translate.
      Note: To use the Enable Workflow for Sidebar or Bulk Translate setting, make sure your XTM app is updated to the latest version.
    5. To create a project using the Entry Sidebar or Bulk Translate in the Full Page app, check the From Sidebar or Bulk Translate in the Full Page UI checkbox, and select a role from the Select Roles dropdown.
    6. To create a project using the Content Types Bulk Translate in the Full Page app, check the Content Types Bulk Translate in the Full Page UI checkbox, and select a role from the Select Roles dropdown.
      Note: Only users with the selected roles will have access to Create Project from the Full Page Location and Entry Sidebar. By default, only the Stack Owner and Admin have this permission.
    7. Version Naming: You can append the master locale to the version name, making it easier to identify and track different versions across locales.
      Syntax: sourceEntrylocale_sourceEntryversion_targetEntryVersion
      For example: en-us_1_3
    8. Character Limit Validation: Translators can now view both maximum and minimum character limits directly within the XTM dashboard.
    9. 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.
    10. If you select the Enable Additional Settings option, you can define the scope of your fields for translation.
  4. Click the Next button.
  5. Additional Settings: Define field exclusions or inclusions, language mappings, and trigger URLs to fine-tune translation behavior.
    1. Exclusions: You can specify which fields or languages should be excluded from the translation process:
      - Content Type Field Mapper: Define specific fields within a particular content type that you want to exclude from translation. For example, you can select specific fields (e.g., multi_line, date) within a content type to prevent them from being sent to XTM.
      - Field(s) to Exclude from All Content Types: Define fields that should be excluded from translation across all content types. For example, excluding title and url ensures these fields are never translated in any content type.
      - Select Field Types to Exclude: Automatically exclude fields based on their field type. For example, selecting Number will filter out and exclude all number-type fields across content types from 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 uses the target language code for exclusions.
    2. Inclusions: Specify the fields that should be included for translation within a content type.
      Content Type Field Mapper: Define fields of a particular content type that you want to explicitly include in translation. For example, you can select specific fields such as name or item_description within a content type to ensure only those fields are translated.
      Note:
      While mapping Modular Blocks, use syntax such as:
      modular_blocks[].block_a.heading: Sends all instances of block_a.heading inside modular_blocks to XTM.
      modular_blocks[0].block_a.heading: Targets only the first instance.
      Do not use an index and empty brackets together. For example: modular_blocks[0].block_a.group[].title is invalid.
    3. Language Configuration: Define the content translation languages for XTM and Contentstack to avoid any mismatch between the language codes.
      Click the Add Language button to add a language. All entries from XTM languages will be localized into the corresponding Contentstack languages.
      For any target languages not selected, the app uses the default language code of the stack.
      Exclude Languages: Select the language(s) from the dropdown that you want to remove from the Language dropdown in the sidebar.
    4. Set Up Trigger URL: Configure your endpoint to receive automatic triggers from XTM. A POST request is sent when a project is created, and a GET request is made when the project is completed.
  6. Once done, click Finish.
  7. If you want to reset the configuration settings, click the Reset Configuration button. A popup will appear. Click the Reset Config button to reset the entire configuration.
6. After adding the configuration details, click the Save button.
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 locations and webhooks, refer to the Installed Apps guide.
Use the XTM App for Machine Translation
To create projects for translation using the XTM app, you can use Workflow, Entry Sidebar, and Full Page Location.
Using XTM in a Workflow
To use XTM in a workflow, log in to your Contentstack account and follow the steps given below:
Note: We assume that you have created a workflow in step 2 and then configured the workflow and workflow stages under Contentstack Fields in the XTM app configuration in step 3.
1. Navigate to Entries from the header and open the entry you want to translate. Then click the “Workflow Details” icon from the right navigation panel.
2. To initiate the translation process, change the workflow stage as defined in the app configuration in step 3 by clicking the Change button.
3. Select the next workflow stage from the Set Workflow Stage dropdown. For instance, after Draft, select the Send for Translation stage to create a project and initiate the translation.
4. You can also set a due date, assign to users or roles, add comments, and then click the Update 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.
Using the XTM App as an Entry Sidebar
To use the XTM app as an Entry Sidebar, log in to your Contentstack account and follow the steps given below:
1. Navigate to Entries from the header and open the entry you want to translate. Then click the “Apps” icon from the right navigation panel.
2. Select XTM from the dropdown and fill in all the fields under the Translate tab.
  1. Project Name: Enter the project name to create a project for translation.
  2. Select the Language or Template option:
    1. Language: If you want to use Language, choose the respective radio button. Then select the locales from the Language dropdown, and choose the Filter Template.
      If Auto Assign Template is configured under XTM Fields during app configuration in step 3, it will be selected by default in the dropdown. You can also select any template from the dropdown.
      Enable the Exclude XTM Workflow toggle button if you want to exclude the XTM Workflow configured under XTM Fields during app configuration in step 3.
      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. Entry References: You can add referenced entries for translation directly from the sidebar by clicking the Entry References button.
    In the Translate Referenced Entries modal, select the referenced entries and click Save.
  6. 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.
    Note: Manage Fields settings will be saved for only one instance.
  7. Files to Import: You can import multiple reference files for translation by clicking the Files to Import button.
    Note: Total size must not exceed 5 MB.
  8. Translate: Click the Translate button to complete the project creation and start the translation process.
3. You can view the translation status under the Status tab by selecting a project using the Select Project dropdown. This dropdown holds the Project Name of the translation projects.
  You can view the status of your project, and the date and time of update under the Project Status section. Click the vertical ellipses to Cancel or Reanalyze your project.
  Note: When you click Cancel, the project deactivates only in the XTM portal. The localized language remains as it is.
  In the Language Status section, you can view the status of the individual language you selected. Click the vertical ellipses to use the View Error (in case of errors), Open Entry, or Cancel options.
  Note: You can view the translation status of up to 10 recent projects in the XTM dashboard.
4. After successful translation, you can view the translated content in the entries.
Using XTM as a Full Page Location App
To use the XTM app in Contentstack, log in to your Contentstack account and follow the steps below:
1. Navigate to the stack dashboard, click Apps from the header, and select the XTM app.
2. You can view the XTM app within your CMS.
  Note: Bulk Translate lets you choose specific entries from a content type to send for translation, while Content Types Bulk Translate sends all entries of selected content types for translation at once.
3. The Bulk Translate feature sends selected entries for translation and tracks them in one place. To translate content using this option, follow the given steps:
  1. Select the Content Type for translation.
  2. Select entries for translation.
    Note: You can translate up to 500 entries (including locale versions) at once.
  3. After adding the entries, click Show Selected to view all the entries added for translation.
  4. To initiate the translation process, click Translate.
  5. In the Confirm Translation modal, fill in the details as follows:
    1. Provide the Project Name for the translation.
    2. Select the Language or Template option:
      1. Language: Click the Language option, then select a Language and a Filter Template from the respective dropdowns.
        If Auto Assign Template is configured under XTM Fields during app configuration in step 3, it will be selected by default in the dropdown. You can also select any template from the dropdown.
        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. Set the date and time in the Due Date (optional) field for the translation process.
      Note: The Deadline Date format is mm:dd:yyyy, and the time format is hh:mm:ssZZ, where ZZ refers to the time zone.
    4. Enter the Description (optional) for the XTM translation project.
    5. Under the Files to Import section, you can import reference files for translation.
      Note: Total size must not exceed 5 MB.
    6. Once these details are added, click the Translate button.
4. The Content Types Bulk Translate option translates all entries across selected content types at once. To translate content using this feature, follow the given steps:
  1. You can Create a Project by providing the Project Name for the translation.
  2. Select Content Types from the dropdown. You can add multiple content types for translation at one go.
  3. Select the Languages or Templates option:
    - Language: Choose the respective radio button. Then select the locales from the Language dropdown, and choose the Filter Template.
      Note: You can add multiple locales for translation at once.
    - Template: Choose the respective radio button and select the template provided in the dropdown.
  4. Enable the Is Content Type Specific toggle to create a separate project for each content type in the XTM dashboard. Each project will be named using the format <Project_Name Content_Type_UID>. When disabled (default), all content types are grouped under a single Project Name as specified.
  5. Set the date and time in the Due Date (optional) field for the translation process.
    Note: The Deadline Date format is mm:dd:yyyy, and the time format is hh:mm:ssZZ, where ZZ refers to the time zone.
  6. Enter the Description (optional) for the XTM translation project.
  7. Once these details are added, click the Create Project button to initiate the translation.
5. To view the translation status of the entries, click Project Status from the left panel.
  To view the stack-specific project statuses, select the Stack-specific Projects dropdown option. By default, the All Projects option is selected.
  Note: You can also view the translation status in the XTM project dashboard.
6. To view the detailed status, click the vertical ellipses under the corresponding Actions section and click View Details.
7. You can check the elaborated translation status of the entry.
8. Click Audit Logs to view all types of logs: Error Logs, XTM Logs, and Contentstack Entry Logs.
9. To edit, click the vertical ellipses under the corresponding Actions section to edit the entry or view its details.
  1. Select Open Entry to go to the entry page.
  2. Select View Details to get the detailed error.
  After successful translation, you can view the translated content in the entries.
Use the XTM app for Human Translation
Human translation in XTM allows an individual user to manually translate content. This process is slower than machine translation.
To translate the content manually using the XTM app in Contentstack, log in to your Contentstack account and follow the steps below:
1. Navigate to Entries from the header and open the entry you want to translate. Then click the “Apps” icon from the right navigation panel.
2. Select XTM from the dropdown and create a project. Under the Translation tab, select the Language option, provide Project Name, choose Languages from the dropdown, select the Filter Template, and then click Translate.
3. In the entry sidebar, go to the Status tab. You can view your Project Name in the Select Project dropdown. Copy it to the clipboard to use in XTM.
  Note: The Project Name is a unique identifier for the entry. It allows users to easily locate the entry in the XTM dashboard for manual translation.
4. Navigate to the XTM dashboard to view all projects. Select the project corresponding to your Project Name.
5. In the left navigation panel, click Workflow. Assign different languages to different users to translate the content manually and then click the Start button.
  Note: Users must log in with individual credentials. Human and machine translation use separate credentials in XTM.
6. Select the project based on the Project Name and manually translate the content. Once completed, the translated content will be saved automatically and appear in Contentstack.