1. Introduction

This document describes all relevant steps to install the translationstudio Application.

1.1. Requirements

Please consult the translationstudio

for a detailed list of requirements.

1.2. Components

This application is the core of translationstudio. It is designed as a daemon (GNU/Linux; Linux in the following) or service (Microsoft Windows) and makes it unnecessary for the CMS to talk directly to a Translation Memory System (TMS).

1.2.1. Security Issues

Please make sure that the port both programmes use for communication is accessible and not blocked by a firewall. In addition, if the translationstudio Application runs on a different server, both servers have to be able to communicate with each other. Finally and importantly, please make sure that the port used by the translationstudio Application is not publicly accessibly but only within your network, and preferably limited to those servers requiring it, according to your security policies.

2. Installation

The installation process consists of four steps:

  1. Deploying the translationstudio application

  2. Choose a database server mode

  3. Installing the translationstudio Application

In the following, it will be assumed that the translationstudio Application will be installed on the CMS server as well. How to install it on different servers will be described where appropriate.

translationstudio supports different databases. The installation procedure described below assumes that a non-embedded database server will be used.

2.1. Installing translationstudio

The way you install the translationstudio Application depends on the operation system of the server you are installing on and whether the CMS system is located on the same server or on a different server (same server installation vs. different server installation). If you are installing on different servers, the installation guide will give you special information for handling that scenario whenever necessary.

2.1.1. Deploying the translationstudio Application

translationstudio provides different ZIP files for a Microsoft Windows or Linux installation.

First, extract the appropriate release archive file to any directory.

In the following, we assume that the archive has been extracted to

C:\translationstudio\install\temp

for Windows or

/home/fs5/translationstudio/install/temp

for Linux.

The extracted folder contains the application’s folder translationstudio, which should be moved to a separate target directory, e.g. to

/opt

Thereafter, the application’s home folder will be

/opt/translationstudio

2.1.2. Choosing a Database

translationstudio can use either of the following databases:

  1. Embedded H2 Database

  2. MySQL

  3. MS-SQL

  4. PostgreSQL

By default, an embedded database will be used. translationstudio supports a test mode in which an embedded in-memory database will be used (this allows for POCs and other quick tests).

Embedded and Non-embedded Databases

It is possible to switch between the embedded and an non-embedded mode by editing the configuration-application.xml file and changing the value of use-embedded-database to either true or false.

<property name="use-embedded-database" internal="use-embedded-database" value="false"/>

In addition, you may use an in-memory only database. To do so, set use-embedded-in-memory from false to true. Importantly, all data will be lost once the application is closed! Use with caution.

<property internal="use-embedded-in-memory" name="use-embedded-in-memory" value="true"/>
Running translationstudio with a test license will only allow you to use the embedded in-memory database mode. This cannot be changed.

It is possible to browse the embedded database by downloading a H2 jar library from the H2 Database Engine homepage. Downloaded and deploy the binary jar to the data directory and either double-click the file (Windows) or open a terminal, navigate to the data folder and type

java -jar <h2-jar-file.jar>

This will open a web browser which allows you to connect to the database file using the JDBC URL jdbc:h2:./translationstudio Remove username and password and click on the connect button.

translationstudio has updated the H2 databse version from 1.x to 2.x which may lead to incompatible databases. You may want to downgrade to version 1.4.200 again if need be.
Using a Database Server

Although this step requires a deployed translationstudio application, the database configuration will be described here to avoid repetition later.

After having deployed the application (in this example: /opt/translationstudio), please edit the file conf/configuration-application.xml and set the following property to true:

<property name="use-embedded-database" internal="use-embedded-database" value="false"/>

translationstudio uses Hibernate to connect to its database. Consequently, you have to provide a file called conf/hibernate.cfg.xml.

You may choose a sample file from the examples directory. Each file will look quite similar and contains identical placeholders which have to be adapted to your infrastructure:

  • @database_server@ represents the server’s address or IP.

  • @database_port@ represents the port to use

  • @database_name@ represents the target database name (e.g. translationstudio)

  • @database_user@ represents the database user used by translationstudio

  • @database_password@ represents the password of the user provided.

This document does not explain how to create or setup a database. Please contact your administrator and request the respective information.

For Microsoft SQL Server: You can leave out the port if you are using the standard port. You can also skip the instance name if you are not using named instances. Make sure that the database server accepts connections via TCP/IP.

Please download the appropriate JDBC driver.
MySQL
PostgreSQL
Microsoft SQL Server

The JDBC driver (its JAR) has to be deployed to the ./lib folder inside the translationstudio folder. The required JAR may be obtained from your administrator or from various online resources such as those listed above.

You do not need to create tables yourself. translationstudio will create/update tables itself. All it needs is an existing database/schema provided in the ./conf/hibernate.cfg.xml file.

2.1.3. Installation on a Linux Server

Please note: The program sudo must be installed on the server.

Depending on the scenario (same server or different server) we assume different preconditions.

Same Server

  1. The translationstudio Application will be installed in /opt/translationstudio

Different Server

  1. The CMS is installed on server A with the IP 192.168.0.1 (here).

  2. The translationstudio Application is installed on server B with the IP 192.168.0.2 (here) in the directory /opt/translationstudio

To install the translationstudio Application, execute the following steps:

  1. Make the file /opt/translationstudio/translationstudio executable, e.g. using the command chmod 755 /opt/translationstudio/translationstudio.

  2. Copy the license file ts-license.conf to the conf directory, e.g /opt/translationstudio/conf.

The translationstudio Application must be able to access (read) the JAR, so please provide sufficient file permissions.

By default, translationstudio will be executed by the user fs5. Create the user if necessary (or use the install script, see below).

The user needs read and write privileges on all files in the directory /opt/translationstudio/ and all subdirectories. In addition to that, the script translationstudio must be executable as described above.

Importantly the user fs5 might be added to the sudo group. To do so, enter the following command usermod --aG sudo fs5

To make the translationstudio Application start at boot time and shutdown when the system stops, you can use the installation procedure provided by translationstudio. To do so, open a terminal and navigate to /opt/translationstudio/.

Please check user and group

translationstudio uses the user and group fs5. If you want to change these, please edit the script translationstudio and change

SERVICEUSER=fs5
SERVICEGROUP=fs5

accordingly.

Please verify the application path

translationstudio assumes to be installed to /opt/translationstudio. If you changed the location, please edit the script translationstudio and change

pidFile="/opt/translationstudio/translationstudio.pid"

accordingly.

Thereafter execute the command

./translationstudio install

using root privileges.

Root privileges are needed to create a symlink in /etc/init.d only.
The application itself will always be started with a specific user (see script file), usually fs5. translationstudio itself will be startet via
su fs5 -c "java …​"

If the installation succeeds, the service will be started at boot time and stopped when the system is shut down. If a problem occurs, you may either analyse the messages printed on the screen or follow the install instructions as stated in the respective section using the following command

./translationstudio --help

If you are running the database server and the translationstudio Application on the same server, please make sure that the database server (here: mysqld) is started prior translationstudio.
To do so, edit the script /opt/translationstudio/translationstudio and change line 4 from
#Required-Start: $remote_fs $syslog
to
#Required-Start: $remote_fs $syslog $mysqld

Now, follow the steps below:

First, decide on the port to be used. translationstudio uses port 1235 by default. If you want to change it, please edit the configuration file ./conf/configuration-application.xml and change the value of

<configuration-application>
  ...
  <property internal="MinaPort" name="application-port"
  value="1235"/>
</configuration-application>

to any port you like. It might be advisable to choose a port between 49152 and 65535 as these are not registered or reserved by IANA.

Second, start the service with the following command in case you have used the insserv utility in the previous steps (You will respective privileges to start the service):

service translationstudiod start

The application itself will always be started with a specific user, usually fs5. This user is defined in the translationstudio script an can be changed if necessary (not recommended, though).

Finally, if you experience any problems, you may start the translationstudio Application in console mode which will print every log message to the terminal as well. To do so, execute the following command

./translationstudio console

If you are not comfortable with the given installation process (i.e. with required privileges) you may have a look at the script translationstudio to check what translationstudio actually does.
You may even follow a step by step install instruction via ./translationstudio --help

2.1.4. Installation on a Microsoft Windows Server

Depending on the installation scenario (same server vs. different server) we assume different preconditions.

Same Server

  1. The translationstudio Application will be installed in C:\translationstudio.

  2. The CMS is installed on the same server and is accessible via localhost.

Different Server

  1. The CMS is installed on server A with the IP 192.168.0.1.

  2. The translationstudio Application is installed on server B with the IP 192.168.0.2 in the directory C:\translationstudio

Now, copy the license file ts-license.conf to the conf directory, e.g C:\translationstudio\conf.

At this point, a database server will be made available to translationstudio. If you want to use the embedded database, please skip the following steps.

Install the translationstudio Application in the operating system by using the command line tool install_service.bat as administrator and follow the steps below.

(1) translationstudio uses port 1235 by default. If you want to change it, please edit the configuration file ./conf/configuration-application.xml and change the value of

<configuration-application>
  ...
  <property internal="MinaPort" name="application-port"
  value="1235"/>
</configuration-application>

to any port you like. It might be advisable to choose a port between 49152 and 65535 as these are not registered or reserved by IANA.

(2) Start the service from the Windows Service Console.

You can start translationstudio from the command line by executing console.bat. You can shutdown the application by opening http://localhost:1235/translationstudio in your browser.

2.1.5. Security Considerations

By default, translationstudio exposes its REST API via HTTP only. This is not an issue in a same server scenario in which all requests are limited to the host system

translationstudio encrypts sensitive data (such as credentials) by default.

Unfortunately, translationstudio cannot be released with a valid certificate, because the server hosting translationstudio usually does not have an URL (but rather an IP).

You can, however, (optionally) activate TLS encryption.

You will probably have to make use of self-signed certificates. Let’s Encrypt provides extensive documentation about how to create and install your own certificates.

To do so, please edit the following settings from ./conf/configuration-application.xml to provide all necessary information:

<configuration-application>
  ...
  <property name="tls-keystore-file" internal="tls-keystore-file" value="" />
  <property name="tls-keystore-type" internal="tls-keystore-type" value="JKS" />
  <property name="tls-keystore-password" internal="tls-keystore-password" value="" />
  <property name="tls-certificate-password" internal="tls-certificate-password" value="" />
  <property name="tls-algorithm" internal="tls-algorithm" value="ssl.KeyManagerFactory.algorithm" />
  <property name="tls-protocol" internal="tls-protocol" value="TLS" />
</configuration-application>

  • tls-keystore-file
    Path to the keystore file which contains the certificate to be used.

  • tls-keystore-type
    (optionally) Keystore type.

  • tls-keystore-password
    The password to access the keystore.

  • tls-certificate-password
    The certificate’s password.

  • tls-algorithm
    (optionally) The algorithm to be used.

  • tls-protocol
    (optionally) The protocol to be used.

It is advisable to create a unique keystore with a single certificate for translationstudio to use as this keystore will only be used to provide TLS encryption for the REST endpoints.

If connectors establish connections via HTTPS, the required certificates have to be available in the default keystore used by the JDK.

Since the CMS communicates with translationstudio, its host has to trust the certificate used by translationstudio. Therefore, you will have to add it to the list of trusted certificates. Please contact your administrator for further information about how to do this.

2.1.6. Firewalls and Proxy Servers

If your translationstudio application requires to use a proxy to connect to URLs other than your content management system (i.e. for your connectors), you can activate a feature by adding a specific event to your connector event list using the translationstudio configuration interface

First, you need to specify the proxy configuration settings. To do so, create the file ./conf/connector-proxy.properties add the following settings as needed

connector-proxy.properties
proxy.url=localhost
proxy.port=8091
proxy.protocol=direct|socks|http|https
proxy.user=my-user
proxy.password=my-password

translationstudio supports the following proxies:

Proxy Event Class

Generic Proxy
- direct
- socks
- http(s)

com.idmedia.translationstudio.events.ProxyHttpUrlConnection

NTLM Authentication

com.idmedia.translationstudio.events.NTLMProxyHttpUrlConnection

Add the respective event class to your event list using your translationstudio configuration.

You can add update your ./conf/logging.properties file to add fine logging to your proxy by adding the following line

com.idmedia.translationstudio.events.URLStreamHandlerImpl.level=FINE

2.1.7. Memory Management

If you find that a service modules died unexpectedly (either via health report email, logfile entry or via the translationstudio Status Page with one module working for hours), this might be caused by a memory shortage.

Therefore, you may consult the garbage collection logfile (see log directory) which will contain the following startup parameters:

  1. -XX:InitialHeapSize=value

  2. -XX:MaxHeapSize=value

To change these values, please stop the application and continue with one of the following sections depending of your operating system.

Please make sure that you have enough memory available.

We suggest to assign approx. 2.9 GB to the translationstudio Application using the following settings:

-XX:InitialHeapSize=197212416 -XX:MaxHeapSize=3155398656 (ca. 2.9 GB)

Changing JVM Memory - Linux

To change the JVM memory parameters, edit the translationstudio script file and add these parameters to

JVMPARAMS="$MEMORY $OEMDUMP"

e.g.

JVMPARAMS="$MEMORY $OEMDUMP -XX:InitialHeapSize=197212416 -XX:MaxHeapSize=3155398656"

This example will set the initial heap size to 0,18 GB and the max heap size to 2.9 GB.

Changing JVM Memory - Windows

There are two ways to change the memory allocated to the JVM

  1. via TranslationService.exe

  2. by re-installing the service

Running TranslationService.exe will open a configuration panel of the respective Windows Service and allows you to add startup parameters to the Service (see below), i.e. -XX:InitialHeapSize=VALUE -XX:MaxHeapSize=VALUE

You may also change the memory allocated to the JVM by re-installing the service.

To do so, run delete_service.bat first.

Edit the file install_service.bat and add the following String

;-XX:InitialHeapSize=VALUE;-XX:MaxHeapSize=VALUE

e.g.

;-XX:InitialHeapSize=197212416;-XX:MaxHeapSize=3155398656

and append it to the following parameter string

++JvmOptions=-Djava.util.logging.config.file=conf/logging.properties; -Dtranslationstudio_basedir=;-Xloggc:log/gc.log;-XX:+UseGCLogFileRotation; -XX:NumberOfGCLogFiles=10;-XX:GCLogFileSize=10M;-XX:+HeapDumpOnOutOfMemoryError; -XX:HeapDumpPath=log/crash.hprof

e.g.

++JvmOptions=-Djava.util.logging.config.file=conf/logging.properties; -Dtranslationstudio_basedir=;-Xloggc:log/gc.log;-XX:+UseGCLogFileRotation; -XX:NumberOfGCLogFiles=10;-XX:GCLogFileSize=10M;-XX:+HeapDumpOnOutOfMemoryError; -XX:HeapDumpPath=log/crash.hprof; -XX:InitialHeapSize=197212416;-XX:MaxHeapSize=3155398656

Importantly, the ++JvmOptions property value must not contain a blank character.

You may now install the service again by executing install_service.bat.

This example will set the initial heap size to 0,18 GB and the max heap size to 2.9 GB.

Validating JVM Memory

You may validate the settings by opening the log file log/gc.log.0 once translationstudio has been restarted.

2.1.8. Checking the translationstudio Application Status

You may check whether the translationstudio Application is running by opening a browser with the following URL (in the following example, the translationstudio Application will use port 1235 on localhost):

http://localhost:1235/translationstudio/server/status

You should see a status page. If you cannot access the page, please make sure that either the domain and the port are correct or consult the application’s log file.

3. Adding Features

3.1. Creating HTML preview files from translatable XML files

If you do not have a special preview template set / output channel, a special hook allows you to create HTML preview files from translatable XML files.

To add this hook, add the following tmsimport hook class to the translationstudio Application’s conf/hooks.xml file:

<class name="com.idmedia.fts.fs.hooks.basics.CreateHtmlPreview" />

This hook uses the XSLT file cont/translationstudio.xsl to transform a translatable XML file. You can customise this file at any time.

the HTML file will be created for every translatable XML file, no matter if the XML file already has a preview file associated to it.

3.2. Extending translationstudio

It is possible to add new custom features to translationstudio using the API to implement

  • Connectors

  • Hooks

  • Custom input component processors

Please consult the manual on how to extend translationstudio and the respective tutorials for further information.

3.3. Cronjobs

It is possible to add a cronjob to the translationstudio Application. This cronjob will allow you to execute a shell/terminal command regularly. To implement this, create the file

./conf/modules-custom.xml

(if necessary) and add the following XML node to the root services node:

<service class="com.idmedia.translationstudio.module.system.CronjobModule">
    <property name="execute-command" value="./cronscript" />
    <property name="sleep-minutes" value="5" />
</service>

In this example, the cronjob will execute the bash script cronscript every 5 minutes. Adding this to the modules XML may result in the following:

<?xml version="1.0" encoding="UTF-8"?>
<services>
  <service class="com.idmedia.translationstudio.module.system.CronjobModule">
        <property name="execute-command" value="./cronscript" />
    <property name="sleep-minutes" value="5" />
  </service>
</services>

If you want to log the command’s result, please add the following entry to the ./conf/logging.properties file:

com.idmedia.translationstudio.helper.ExecuteShellCommandOperation.level=FINE

You have to restart the translationstudio Application.

4. Adding a new Connector

To deploy the connector’s JAR file, please follow the instructions below. If you use a connector provided by translationstudio, you may skip this section.

  1. Stop the translationstudio Application

  2. Deploy the JAR file to the ./lib-plugins folder

  3. Start the translationstudio Application

5. Troubleshooting

5.1. Application not starting up properly

Sometimes, the log fie does not contain all output from the application. Therefore, you may start it from command line/shell using either

On Linux:
./translationstudio console

or on Windows:
console.bat

5.2. XMLs files are not being created or imported

This situation occurs if either of the respective processes dies silently. The health monitor email will provide you with a list of affected processes in such as case.

Usually, such a situation is related to memory shortages of the JVM and can be solved by increasing the allocated memory.

5.3. A connector cannot connect to a Translation Memory Server

Sometimes, a connector cannot establish a connection to a Translation Memory Server although the network settings are correct and the server should be reachable.

Usually, this happens when the server uses a self-signed certificate or a certificate which is not stored in the JDK’s keystore.

By default, the translationstudio Application will use the JDK’s default keystore, so you have to add the certificate and restart the translationstudio Application.

translationstudio is a product of I-D Media GmbH, Cologne, Germany. All rights reserved, except for the software products listed in the following which are used in accordance with their respective licenses.

Each software package used in translationstudio is legally protected according to the given license information. This product includes software developed by the Apache Software Foundation.

A full list can be found here.