Git: Description & installation and configuration requirements

Description of the connector

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.

Depending on the setup, the Git connector can also return files to a different repository, instead of the original one.

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

At bucket level, you can decide whether to select files for translation, and create an XTM Cloud project, manually or set the connector to process new/updated content automatically at specified time intervals. In the former case, you can create projects in the XTM Cloud UI [XTM Connect → Buckets → Git(click on the context menu of a relevant bucket)Actions → Select files for translation].

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

IMPORTANT!

The exact environment might vary from client to client.


Installation requirements

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

IMPORTANT!

We highly recommend that you arrange for XTM International to host the connector, for a seamless installation and configuration process and to make troubleshooting easier, provided by the XTM International Support team, if there are any issues.

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

MINIMUM SERVER TECHNICAL REQUIREMENTS

MINIMUM SERVER TECHNICAL REQUIREMENTS

RAM: 8 GB

Processor: 2 Core

Operating system: Rocky 8

Hosting service: Apache Tomcat 9.0.39 (recommended 9.0.46)

Database: PostgreSQL by XTM version:

  • XTM 13.3: PostgreSQL 15;

  • XTM 13.1 – 13.2: PostgreSQL 12.

Java Development Kit version:

  • XTM 13.2 – 13.3: v.17;

  • XTM 13.1: v.11.

Firewall configured to permit requests to be sent to XTM Cloud and files to be received from XTM Cloud.

Disk space:

  • 50 GB of disk space for the connector;

  • enough disk space to save the repositories together with all the target language files (approximately 200 GB in total).

Callbacks support: accessible HTTP/HTTPS with SSL port with httpd, nginx, caddy or similar software installed.

Preferred:

  • SSH access (can be through VPN) for XTM Administrator and/or XTM International Support team, for installation, configuration and maintenance purposes;

  • SSH user needs root access.

Network settings: there are two configuration modes controlling communication with XTM Cloud:

  1. Regular → Callbacks are sent to the connector (RC) server from XTM Cloud (default). It requires open HTTP/S ports (80 and 443) for inbound traffic from XTM Cloud servers.

  2. Passive → RC triggers a check for project completion. No specific firewall rules are required for inbound traffic (this is configurable by the XTM International Support team).

One of the following protocols can be used:

  1. HTTPS → used for API calls and Git repository flow (pull, push, etc.);

  2. SSH → used if configured instead of HTTPS for Git flow.

XTM & RC connection:

A two-way connection must be established between XTM Cloud and RC. In general, connectors work using callbacks (API calls are automatically triggered when specific actions are triggered and sent to the RC server address by XTM Cloud). Therefore, the RC server must be reachable from XTM via server address (URL/IP:PORT).

The XTM International Support team will require credentials URL/IP, port, database user, password) that will be configured in the back-end. The database will be prepared by the XTM Cloud database upgraders using the credentials configured as above.

Direct connection:

Direct connections are highly recommended. All kinds of load balancers and middleman services that stand between RC and XTM Cloud are not recommended because they can potentially cause packets to be lost. The consequences of this can, for example, be that translations are not imported back, projects are not created or other unpredictable issues.

Access for XTM team:

For better and faster support services the XTM International Support team, we highly recommend that you grant XTM International employees:

  • root access to the server back-end so they can install the connector,

  • access to the database.

The XTM International Support team should be able to access the database, RC files (many files that can be important during support investigations are stored) and should be able to stop, start and restart the RC tomcat. Moreover, at least one XTM International developer and one XTM International administrator must have access to the server – granting access to more XTM International team members will make the troubleshooting process quicker and more efficient.

Connector maintenance:

If the connector is hosted by the client, they are responsible for the backups, logs and alerting system. The XTM International Support team recommends daily backups and the storing of logs for at least the past month.

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.


Configuration requirements

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.

IMPORTANT!

If a continuous project is set in the bucket configuration, the project will be updated with the new content from this file at the next interval set in the bucket's project creation settings.

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.

IMPORTANT!

If the XTM Cloud project template is customer-specific, ensure that the customer used in that template is the same as the customer used in a particular bucket, otherwise project creation will not work!

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

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

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

IMPORTANT!

If you decide to make use of this feature later in the configuration process, keep in mind that it is only configurable in the back-end, by the XTM International Support team.

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.

There is also an option to create customize paths for target files. See Git: Target path mapping for more information.


Performing update of the XTM connector

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.