Installation Manual

e-Spirit AG

2020-02-20
Table of Contents

1. Introduction

This document describes all relevant steps to install and administer TranslationStudio in FirstSpirit and the associated TranslationStudio Application.

1.1. Requirements

Please consult the TranslationStudio

for a detailed list of requirements.

1.2. Components

TranslationStudio consists of the following components:

  1. FirstSpirit Module (FSM)
  2. TranslationStudio Application

1.2.1. FirstSpirit Module (FSM)

The FirstSpirit Module handles all aspects of the functionality of TranslationStudio that are available within FirstSpirit, such as

  • Configuring the TranslationStudio software with an easy to use configuration panel.
  • Handling of workflows for translation requests.

This module will be installed on the FirstSpirit Server.

1.2.2. TranslationStudio Application

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 FirstSpirit to talk directly to a Translation Memory System (TMS).

1.3. Architecture

While the FirstSpirit Module (FSM) has to be installed and configured using the FirstSpirit ServerManager, the TranslationStudio Application can be installed on any server, unless a sharing of resources is possible.

Both modules, or “programmes”, communicate with each other using a specific port the TranslationStudio Application binds to. The TranslationStudio Application will connect to FirstSpirit using the FS_ACCESS API.

1.3.1. FirstSpirit FSM Module

The FirstSpirit Module (FSM) provides all means necessary to use Translation Studio in FirstSpirit and to communicate with the TranslationStudio Application. However, all parts of FirstSpirit Module work within the context of FirstSpirit and its clients.

1.3.2. TranslationStudio Application

The TranslationStudio Application is the core programme which keeps track of translations, receives information of new translation requests, initiates translations and imports translated data into FirstSpirit. In addition, this programme is also responsible for the entire data management related to a translation, e.g. exporting the respective elements from FirstSpirit.

1.3.3. Shared Resources

The FirstSpirit Server requires write access to the TranslationStudio Application’s working/preview-files/temp directory to deploy generated translation preview files by FirstSpirit.

If the TranslationStudio Application is installed on a server different from the FirstSpirit server, please make sure that the respective folder is available, e.g. using a permanently mounted directory.

1.3.4. 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
  4. Installing the FirstSpirit Module
  5. Configuring the TranslationStudio Module Permissions

In the following, it will be assumed that the TranslationStudio Application will be installed on the FirstSpirit 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 FirstSpirit 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.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.

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

  • The filesystem path of the FirstSpirit installation is /opt/firstspirit5
  • The TranslationStudio Application will be installed in /opt/translationstudio

Different Server

  1. FirstSpirit is installed on server A with the IP 192.168.0.1 (here). The installation directory on that server is /opt/firstspirit5
  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.
  3. Copy the fs-access.jar file from your FirstSpirit installation directory (e.g. /opt/firstspirit5/data/fslib/fs-access.jar) into the folder /opt/translationstudio/lib (you may also use a symbolic link).

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-core.xml and change the value of

<application>
  ...
  <property internal="MinaPort" name="application-port"
  value="1235"/>
</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 file system path of the FirstSpirit installation is C:\Program Files\FirstSpirit5.
  2. The TranslationStudio Application will be installed in C:\firstspirit-translationstudio.

Different Server

  1. FirstSpirit is installed on server A with the IP 192.168.0.1 (here). The installation directory on that server is C:\Program Files\FirstSpirit5
  2. The TranslationStudio Application is installed on server B with the IP 192.168.0.2 (here) in the directory C:\firstspirit-translationstudio

To install the TranslationStudio Application execute the following steps:

  1. Copy the license file ts-license.conf to the conf directory, e.g C:\firstspirit-translationstudio\conf.
  2. Copy the fs-access.jar file from your FirstSpirit installation directory, e.g. C:\Program Files\FirstSpirit5\data\fslib\fs-access.jar, into the folder C:\firstspirit\translationstudio\lib.

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.xml and change the value of

<application>
  ...
  <property internal="MinaPort" name="application-port"
  value="1235"/>
</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-core.xml to provide all necessary information:

<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" />
</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 FirstSpirit server communicates with TranslationStudio, FirstSpirit or 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. 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.7. 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.

2.2. Installing the FirstSpirit FSM Module

The TranslationStudio FSM Module has to be installed on the FirstSpirit Server. To do so, open the FirstSpirit ServerManager, access the server properties and select Modules. Click on the Install button as shown below and follow the steps below.

ServerManager Modules list.
Figure 1. ServerManager Modules list.


A new dialog opens and you have to navigate to the C:\translationstudio\install\temp\module folder (Microsoft Windows) or /home/fs5/translationstudio/install/temp/module folder (Linux) and the FSM file by selecting it and clicking on the button Open as depicted below.

Install the FSM file.
Figure 2. Install the FSM file.


Once the module is installed successfully, you will find the list entry TranslationStudio with several items once expanded.

Select TranslationStudio Service and Configuration from the list and start the service if it has not already been started.

Once the service has started you can configure the module by selecting the module TranslationStudio and clicking on the Configure button. Please select the checkbox to grant all permissions as shown below.

You need to close the FirstSpirit ServerManager and reload it after changing the module permissions.

Granting module permissions.
Figure 3. Granting module permissions.


2.3. Installing TranslationStudio Dashboard and Status Icons

To enable the Translation Status Icon (ContentCreator, Preview) and the Dashboard, you have to add a new global web app component.

To install this web application, access the server properties in ServerManager and select Web applications, click on the add button, choose FirstSpiritJetty and enter the following information:

  1. Id: translationstudiowebapp
  2. Name: TranslationStudio Page Status Icon
  3. Context: /translationstudio
Installing the global web application
Figure 4. Installing the global web application


Now, you can add the TranslationStudio Dashboard and Status Icon component via the Add button.

Thereafter, you have to configure the newly added component by selecting it and clicking on the configure button.

Configuration
Figure 5. Configuration


The only available option to select is Load from TranslationStudio button. Clicking on this will load TranslationStudio’s server and port information as set in the module’s current configuration.

Once loaded, you can close the dialog by clicking on OK. Finally, you can install the new web application by clicking on the Install button as depicted below.

If you change the TranslationStudio connectivity settings, this configuration will not be updated automatically but requires manual updating again.

3. Installing TranslationStudio in a Project

In order to use the TranslationStudio in a project, the following steps have to be reproduced:

  1. Create a new database
  2. Install the project component
  3. Create a TranslationStudio user to access and edit the target project
  4. Grant user permissions
  5. Create a new databse schema
  6. Install templates and structures using the setup script
  7. Import workflows

The user has to be a server administrator. Make sure that nobody is accessing the project configuration (ServerManager) during the installation.

The schema has to have schema-sync enabled.

3.1. Create a new Database

TranslationStudio requires a database which can be added by editing the FirstSpirit ServerManager server properties and by making it available to the target project.

A detailed instruction may be found in the official FirstSpirit Manual for Administrators. You may use a Derby database, although this is not recommended due to performance considerations.

3.2. Install the Project Component

Edit the target project using ServerManager, select Project components from the settings list and click on the add button. A window will open allowing you to choose from a list of various installed components. Select TranslationStudio Project Preparations and click on the OK button.

By adding this project component, a setup script will be created in this project (see below for further information)

Installing a project component. 

You may now store the changes by closing the window using the OK button.

The installation script will only be visible to administrator groups by default. Please change the permissions if necessary.

3.3. Create a TranslationStudio User

Once the project component is installed, you may wish to create a distinct user which is used by the TranslationStudio Application for accessing FirstSpirit.

Please create this user using FirstSpirit ServerManager if required.

The user has be a server administrator.

3.4. User Permissions

Open the SiteArchitect and access the target project to grant the following permissions to all, Page Content/PageStore, Site Structure/SiteStore and Global Settings/Global Content Area:

  • Visible, Read, Change
  • Create object / Create folder
  • Remove Object
  • Show Metadata
  • Change Permission

Note of Clarification

Unfortunately, the TranslationStudio user requires change permission rights in order to use an essential FirstSpirit feature to export and import data from FirstSpirit. TranslationStudio itself will not meddle with your permission settings at any time.

A detailed instruction how to create users may be found in the official FirstSpirit Manual for Administrators. To change or assign user permissions in a project please consult the official FirstSpirit SiteArchitect (Manual for Editors and Project developers).

3.5. Create a new database schema

To create a new database schema, select the template store, right-click on Database Schemata and select Create new schema. In this example, a new schema called translationstudio will be assumed. You may also use an already existing schema.

3.6. Install Templates and Structures Using the Install Script

To create all required structures and scripts, right click on the newly created (or already existing) database schema and execute the script Install or Update TranslationStudio from Execute Script - TranslationStudio in the context menu.

The script will add a database table to the schema, install all required scripts and folders (Site structure, Page content, Data sources, Templates, Global Settings). What is more, the script will also create all neccessaryy scheduled tasks (preview and queue mode).

You can change the preview page output channel to be used (chosen during the installation process) at any time later by editing the generation task entry of the scheduled tastk fts_preview via ServerManager.

Importantly, TranslationStudio requires an assigned meta data template to work properly. If the project does not have a meta data template, the setup process will create a new one. However, it has to be assigned using the FirstSpirit ServerManager.

If a meta data template has been set, the script will add the required section automatically and no further action is required by the administrator. To assign this meta template, open the FirstSpirit ServerManager and navigate to the configuration of your project and select Option from the list. Select the target meta template in the select field Metadata template and click OK.