1. Introduction

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

1.1. Requirements

The TranslationStudio Application has to be installed already. Please consult the TranslationStudio Technical Data Sheet for a detailed list of requirements.

1.2. Components

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.

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

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

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

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

3. Installation

The installation process consists the following steps:

  1. Deploying the FS access jar

  2. Installing the TranslationStudio FSM

  3. Installing the TranslationStudio FragmentCreator MicroApp FSM
    (optionally, only if you want to use TranslationStudio in the FragmentCreator)

  4. Configuring the TranslationStudio Module Permissions

3.1. Deploying the FS Access Jar

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) and restart the application.

3.2. Installing the TranslationStudio FSM

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.

3.3. Installing the TranslationStudio FragmentCreator MicroApp FSM

To make use of TranslationStudio in the FragmentCreator, you have to install the respective TranslationStudio MicroApp FSM in the same way you installed the TranslationStudio FSM module.

All FragmentCreator modules have to be installed already.

Now, create a new global web app and name it tsmicroapp and add the TranslationStudio FragmentCreator CTX web component. Thereafter, you have to edit its web.xml and update the password value in the URL as shown below.

<context-param>
    <param-name>eureka.client.serviceUrl.defaultZone</param-name>
    <param-value>http://cxt_eureka:aaaaa@localhost:8000/fragments/eureka</param-value>
</context-param>

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

4. Installing TranslationStudio in a Project

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

  1. Install the project component

  2. Create a new database

  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

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.

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

4.2. Install the Project Component

You can install TranslationStudio in either

  • FragmentCreator project

  • generic project (non-FragmentCreator)

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.

Generic Project

To install TranslationStudio in a generic (i.e. non-FragmentCreator) project, select TranslationStudio Project Preparations and click on the OK button.

Installing a project component

Installing a project component

FragmentCreator Project

To install TranslationStudio in a FragmentCreator project, select TranslationStudio FragmentCreator Installer and click on the OK button.

Installing a project component

Installing the FragmentCreator project component

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

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.
If you activated the automatic distribution, the install script will be executed automatically once you have added the project component.

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

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

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

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

Selecting a Meta Template
Figure 6. Selecting a Meta Template

Now you can go back to the SiteArchitect and make the necessary changes to the form of the Metadata template as described in the section above.

Avoid Privilege Limitations

Although the meta template is created or the required form fields are added to the existing meta template automatically, a problem might occur if your current user does not have the permissions to change an already existing meta template. In that case, you may have to run the installation script again.

4.7. Configuring Language Mappings

Language mappings are global content pages which allow you to define legitimate source and target language combinations as well as assign a target connector.

A language mapping page uses the page template fts_gca_mapping as shown below:

Creating a new Language Mappings page
Figure 7. Creating a new Language Mappings page

Visibility

The template Language Mappings is configured to be visible by default. That is because you should be able to create new Language Mappings immediately after installation. But we recommend setting the template to hidden, when you have create all language mappings needed.

To do this, open the properties of the template Language Mappings and change the attribute In selection list to hidden.

4.8. Adding a TranslationStudio Report and an Immediate Translation Helper Plugin to the ContentCreator

To add activate the Report and Immediate Translation Helper Plugin, you simply have to add a web component TranslationStudio ContentCreator Extensions to a ContentCreator web application.

This feature is not available in a FragmentCreator project.

You can add this either to the specific project’s ContentCreator app or to the global ContentCreator app.

Project specific web apps increase your server load and it is usually just fine to add this feature to ContentCreator’s global web app.

In the following, the extensions will be added to the project specific ContentCreator app.

Open the FirstSpirit ServerManager, edit the respective project’s properties and select Web components from the list on the left, click on the tab ContentCreator, click on the button Add and select the TranslationStudio plugin entry from the list and click on OK.

Adding TranslationStudio ContentCreator Extensions
Figure 8. Adding a web component

Thereafter, select the active web server, e.g. FirstSpiritJetty. Finally, click on the button Install.

A dialog box will pop up asking you if you really want to proceed. After having confirmed this, you have to click on the button Execute now to start the process. After the installation process has finished, you have to active the web server.

The report component will now be available to your project in the ContentCreator. To use the TranslationHelper plugin, you have to configure the default AWS and/or DeepL connector first.

Further information on how to install and deploy web components may be found in the respective FirstSpirit manuals.

You have to add this web component to all projects that wish to use the TranslationHelper.

5. Automatic Installation and Update in Projects

TranslationStudio can be installed automatically whenever you its project component to a FirstSpirit project. In addition, TranslationStudio can also update its component in your projects automatically whenever you install a new version (via update uses).

All tables will be created/updated and necessary data sources created if necessary. In addition, required templates, scheduled tasks etc. will be added/updated automatically.

5.1. Requirements

To enable this feature, open the TranslationStudio configuration dialog and open the Distribute section.

Using this feature requires a certain degree of "standardisation".

TranslationStudio requires a schema in order to be installed successfully.

5.2. Creating a Generic Database Layer

Every TranslationStudio project requires a database. Automatic distribution requires the very same database layer to be available in every target project.

The layer has to be made available before the project component is added.

5.3. Installing TranslationStudio in a Project

If you want to install TranslationStudio simply by adding its project component automatically, you will have to meet the following requirements:

  • TranslationStudio has to be able to create its own schema by using an already existing database layer. The layer has to have already been added to the project with active schema sync.

  • All target projects have to have the same output channel used for creating preview pages.

you will still be able to trigger the install/update script manually.
You should use translationstudio as schema name to keep things as simple as possible.

5.4. Updating an already Existing Installation

If you have already installed TranslationStudio in all of your projects, you can safely use this feature, because TranslationStudio will be able to find all mandatory components.

6. Adding Features

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

7. Adding a new Connector

A connector basically consists of 2 parts. A FirstSpirit Connector module FSM and a connector JAR file to be deployed to the TranslationStudio Application.

7.1. Adding a new Connector Module

To install a connector’s FSM, please follow the instructions below.

  1. Open ServerManager and navigate to the modules section.

  2. Install or update your connector’s FSM

  3. Re-open ServerManager

Now, you can configure the connector using TranslationStudio’s configuration gui.

Thereafter, the connector can be selected from the Connector list in the respective language mappings template.

7.2. Deploying the Connector’s JAR file

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 folder

  3. Start the TranslationStudio Application

8. Troubleshooting

8.1. Corporate Content

In general, TranslationStudio works fine with CorporateContent.

You may want to consider using TranslationStudio’s automatic installation and update feature (see above).

If you use CorporateContent and publish versions of TranslationStudio from its own project, please read the following sections carefully.

Do not change reference names

Do not alter the reference names of your CorporateContent package, e.g. by adding the package information to it resulting in reference names similar to refname@package.

8.1.1. Preparing Languages

Let’s say your TranslationStudio template project uses EN as a master language. Now, you want to setup a new project which needs TranslationStudio but which uses EN_GB as a master language.

Although it will not be a problem to transfer all necessary templates, the language mappings in TranslationStudio’s database templates will cause problems, because FirstSpirit will not update language mappings of language independent fields automatically, i.e. although the input components only use language independent fields, the language association will not be updated.

All you have to do is to add the new language to the TranslationStudio project (EN_GB in this example) and update the TranslationStudio database template’s language mappings manually.

Make sure all master languages are available and mapped to the table fields
Figure 9. Make sure all master languages are available and mapped to the table fields

8.1.2. Creating a Template Package

Create a subscription package which contains all of TranslationStudio’s templates, database and workflows. Relevant objects can easily be spotted as they are kept inside individual TranslationStudio folders.

Selected objects contain TranslationStudio folders
Figure 10. Selected objects contain TranslationStudio folders

Subscribing projects might have their own master language. It is essential that this master language is also available in the project offering the subscription packages. FirstSpirit will not update any table template language mapping.

8.1.3. Creating a Global Content and Site Structure Package

Each project using TranslationStudio requires the TranslationStudio workspace site structure folder and the TranslationStudio language mappings global content folder.

Gloal Content Area Folder
Figure 11. Global Content Area Folder
Structure
Figure 12. Structure

Therefore, create a package which allows to transfer these folders as well.

8.1.4. Copying Required Scheduled Tasks

Unfortunately, scheduled tasks (see ServerManager) cannot be transferred using CorporateContent but have to be copied into the target project manually:

  • fts_create_preview_files

  • fts_preview

  • fts_queue

8.1.5. Post Installation/Update Verification

You may wish to verify that all settings have been updated correctly. To do so, navigate to the TranslationStudio scripts, open the "Form" tab and click on the "eye" icon left to the magnifying glass icon. The only field framed in red should be the mappings reference field. If this is the case, all is fine.

Reviewing the form defaults
Figure 13. Reviewing the form defaults

8.1.6. Final Tasks

If you did not provide language mappings (global content area) via a subscription, you have to create those as well.

8.2. 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 AG, 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.

PACKAGE LICENSE LINK

Apache HttpClient

Apache License
Version 2.0

https://hc.apache.org/httpcomponents-client

FirstSpirit API

Apache License
Version 2.0

https://www.e-spirit.com

Jetbrains Annotations

Apache License
Version 2.0

http://www.jetbrains.com/idea/documentation/howto.html

10. Additional Help

The Technical Support of the e-Spirit AG provides expert technical support to customers and partners covering any topic related to the FirstSpirit product. You can get and find more help concerning relevant topics in the FirstSpirit community.