Introduction

XTM Connect – Git (one of the so-called repoconnectors) is a plugin for XTM Cloud and XTM Suite. It connects directly to Git repositories to automate the sending of new or changed content to XTM Cloud and creating translation projects. Then, once the project workflow has finished, it returns translated content to the repository.

The benefits of the connector are:

• reduction in manual tasks,

• cost reduction,

• reduction of turnaround time,

• reduction of human errors.

The use of this connector is provided under the terms and conditions of a separate license. To learn more about the connector, request a quote from our Customer Success department: sales@xtm.cloud.

When you have purchased the connector, XTM Support will enable the API connection for you.

How does it work?

General mechanism

The connector is configured to connect with a repository, and it synchronizes the data at a specified time interval. At the moment of synchronization, Git identifies files that have been updated or added to the repository since the last synchronization and creates copies of their content as "tasks".“ The tasks are then used to create projects in XTM Cloud, using a template predefined there. When translation is finished, XTM Cloud returns the translated files to Git,which in turn returns them to the original repository, and the cycle is finished until the Git repository is updated.

The figure below shows a simplified data flow with use of the Git connector.

Open

Communication

The Git connector has been developed in Java. The connector uses the JGit library to communicate with Git repositories. It uses JGit equivalents of the Git commands.

Git can be used with both Cloud and standalone versions of XTM Cloud. For communication with XTM Cloud, the connector uses XTM SOAP and REST API requests.

The figure below shows a detailed data flow in which the Git connector is hosted in the client'’s internal network (a firewall red line indicates the border between the internal network and the Internet).

Open

The connector can be deployed on the client's server (on-premise) or be hosted by XTM International (remote).

If the connector is installed on the client's server, the client must fulfill the following technical requirements:

After purchase, an XTM International specialist will install all required software on the server. This will include the XTM Connect application. After installation and configuration, they will test the connection.

To configure your connector, collect the required data that is listed below and create a suitable ticket for the XTM International Support team (see Connectors Support).

Client details

1. Client name used for logging into the XTM Cloud platform.

2. XTM Cloud user ID or username. We recommend that you create a new user specifically for the connector so that it is simple to track the connector's activity separately from manual actions by other users. The user in question needs the Project Manager role.

Repositories

The connector can connect to multiple repositories. If you want to configure multiple repositories, provide a list of them with the following data for each:

1. Name of repository;

2. Repository URL;

3. Authentication data to log in to the repository (depending on the authentication protocol):

• HTTPS/Access token: Git username, token, Git URL;

• SSH: Git URL (it should start with git@… or ssh://…).

Synchronization

Buckets will collect files for translation automatically when scheduled so frequent synchronization with repositories is not required. We suggest a minimum 5-minute interval between synchronization events with repositories.

If a file that has already been synchronized has been updated and synchronized again, and a translation project has not yet been created in XTM Cloud, Git will create a task with this updated source file.

When a file that has already been synchronized has been updated and synchronized again, and a translation project has been already created in XTM Cloud, translation of the previous version of the file will be completed in XTM Cloud and the updated version of the file will then be sent for translation in the next project created in XTM Cloud.

Project creation in XTM

1. Base name for the project: A project created by the connector will always be named in the same way but with a sequential number added to the base project name.

2. Customer ID: You can check the customer's ID in XTM Cloud, in the Customers tab. Place your cursor on the icon to display the customer ID and other information.

3. Template ID: Git takes almost all project data from a specified XTM Cloud project template, with the exception of the project name and language combinations. You can check the project template ID in XTM Cloud, in Projects → Templates. Place your cursor on the icon to display the project template ID.

4. Language combinations: Multiple target languages can be used.

5. Project creation schedule: You can choose multiple times and days of the week for creating a new project in XTM Cloud based on synchronized files.

6. Project creation method: When synchronization intervals are different from the project creation schedule, several synchronizations can be performed before the project creation. You can have:

• One project that includes files from all the synchronizations.

• Multiple projects. Each project includes only source files that were discovered after the previous synchronization and before the next one.

• One project that only includes files that were added or modified before the last synchronization. The project will not include files discovered during previous synchronizations.

  • Example: If 10 files have been added to the repository between two scheduled project creation events, and two synchronizations were performed during that time, with the first synchronization discovering 4 new files, and the second synchronizations discovering 6 new files, the project will include 6 source files. The 4 files from the first synchronization will be ignored.

File name specific target languages

There is an option to set project target languages on the basis of language codes included in source file names. In such a case, source files are grouped into projects with the same target languages. Target languages are differentiated from filenames by means of regular expressions. This method lets you translate files from the same branch into different target languages.

Example:

• File1_es_pt.xml into Spanish and Portuguese,

• File2_de_fr.xml into German and French.

Accurate patterns must be provided to XTM International Support to set correct rules and languages. In addition, the specified target languages must be unambiguous.

Example:

• File names that include "_es" are meant to be translated into Spanish (Spain), "_pt" into Portuguese (Portugal), otherwise it is unclear whether "_fr" should be set to French (Canada) instead of French (France) or a different language variant.

Workflows with pre-processing

• New source language: specify the pivot language into which the source files will be translated before they are translated into the project’s target languages.

• Define what will happen to files after the post-processing workflow step:

  • Default: after pre-processing has been completed, the files are sent to the repository with a changed name.

  • Replace source: after pre-processing has been completed, the files replace the original source files in the repository.

  • Do not send: after pre-processing has been completed, the files are NOT sent back to the repository.

Target files delivery method

Select the translated files delivery method that you want to use:

• Create a sibling directory using target language → It creates a new folder with the target language code and pushes target files to that new directory.

• Rename a file using target language → It adds or modifies the target language code in the file name.

• Overwrite source files → It replaces the source files with the translated files.

• Select a target branch → It moves the translated files to a specified branch.

When files translated via Git are modified manually, the connector creates a copy of them with a timestamp in the name and then sends them for translation. Consequently, By doing so, the original, manually modified, file remains unchanged an translation for it is provided in the renamed file. This protects you from file version conflicts.

For us to perform update of your instance of the XTM connector, check the following:

1. The minimum amount of free space on your XTM server should be 30GB.

2. The VPN and server accounts used by the XTM team to access the server are still active and have not been blocked.

3. Ensure and confirm that the operating system was updated at least 2 months ago.

4. The XTM team performing the upgrade process can use root privileges. If, for any reason, that is not possible, we need to have the support of your technical team to perform administrative operations on the server during the upgrade.

5. Prior to the upgrade, perform a speed test by downloading the following file: http://i.xtm-intl.com/random200m. To do this, use the following command: time wget -O /dev/null (Linux systems only). If the download takes longer than 1 minute, notify us about it.