Administration Manual

e-Spirit AG

2020-02-20
Table of Contents

1. Introduction

TranslationStudio allows you to easily file translation requests without the need for later manual intervention.

At its core, TranslationStudio distinguishes between urgent translation requests (which will be processed immediately) and regular requests which will be processed if certain quotes are met.

A preview page might be very helpful as it provides additional contextual information which might aid the translator. Preview pages can be generated from an existing output channel (such as PDF). If your project does not have any eligible channel, you may consider adding one, if necessary.

Preview pages, however, are not required by the TranslationStudio in order to work properly. Rather, it is a feature which provides more contextual information to the translator.

In addition, TranslationStudio allows you to define how many pages and datasets should be included in one translatable XML file. This is a crucial aspect, because

  1. Exporting a page requires FirstSpirit server resources
  2. FirstSpirit pages will be packed in one XML file which is submitted to the Translation Memory System.

The latter aspect is of particular importance, because it allows you to control certain thresholds which guarantee a most efficient translation process. For example, too many files might increase the time needed for translation and splitting files might allow more translators to work on them at the same time.

TranslationStudio is very flexible and offers you a variety of means to customise its usage according to your specific needs. Most of these needs can be operationalised using a proper configuration of your module or workflows.

2. Configuring TranslationStudio

TranslationStudio can be self-hosted in your on-premise environment or hosted in a cloud.

If self-hosted, you may access TranslationStudio’s complete configuration panel by opening the ServerManager’s server properties and selecting Modules. To configure the service, select the item TranslationStudio Studio Service from the list and click the Configure button as depicted below.

Configuring the service itself
Figure 1. Configuring the service itself


If hosted in a cloud, you cannot access server properties but configure TranslationStudio by navigating to and configuring the TranslationStudio project component.

It does not matter (nor does it make a difference) which project component you use to access the configuration.

If you configure TranslationStudio via the project component, you do not need to consider certain settings such as connectivity because these information will be administered by your hoster. Hence, you can focus on only those aspects necessary to customise your TranslationStudio instance according to your needs.

You can configure the module at any time. Any changes stored will be sent to the TranslationStudio application automatically.

Make sure to configure TranslationStudio and send it to the TranslationStudio application. If TranslationStudio has never been configured, it will start with a configuration template to make editing easier. Yet, it will be unable to connect to FirstSpirit and actually process your requests.

2.1. Connections

This settings category allows you to configure the connection settings necessary for FirstSpirit to communicate with TranslationStudio and vice versa.

Connectivity Settings
Figure 2. Connectivity Settings


Please provide the address and port FirstSpirit will use to access the TranslationStudio Application.

Please provide only the IP or server name. If you use names instead of IP addresses, make sure that the TranslationStudio server can resolve the FirstSpirit address. In addition, FirstSpirit has to be able to resolve the TranslationStudio address.

You can test the connections by clicking on the respective Test Connection button.

TLS/SSL should only be used if you installed TranslationStudio with TLS encryption - simply checking the box does not automatically activate TLS in the TranslationStudio Application.

The TranslationStudio Application uses the given FirstSpirit user to access the respective projects. Make sure that this user has project access to all projects using TranslationStudio.

2.2. Management

TranslationStudio has two processes which can be scheduled independently from one another:

  1. Sequential Iteration Process
    This process processes translation requests, checks for quotes, creates translatable XML files and forwards them to a connector
  2. In Translation Monitoring
    This process regularly queries the translation status of all files forwarded to a connector and downloads the translated documents if the translation has been completed.

Depending on your workload and translation timings it might be a good idea to configure the scheduling. By default, each process will be executed after a one minute break.

Usually, translations take longer and it might be enough wait for 1h between two translation checks.

These settings can be used to control the workload. Since exporting and importing data from and into FirstSpirit might impose significant workload on the server, you may want to avoid intense workload during your office hours. These settings allow you to consider such necessities.

Management
Figure 3. Management


2.3. Mail

TranslationStudio distinguishes between three kinds of mails:

  1. Notifications on translation requests and status changes
  2. Error messages popping up during any operation (will be sent to the administrator’s email address)
  3. Additional mails such as connector notifications or health service emails
Mail Settings Category.
Figure 4. Mail Settings Category.


You can test the connection and send a test e-mail to the administrator by clicking Test Settings.

The Receive Notifications section allows you to fine tune which kind of emails you would like to receive. By default, a notification will be sent to each user who requested a page or dataset to be translated. Whenever a status change occurs to this page, an email will be sent to the user if provided in the FirstSpirit user configuration. However, you may also only send all email notifications to the administrator’s email. Finally, you may also deactivate any user notification by sending notifications to nobody.

Information on the Mail Server

User notifications use FirstSpirit’s email settings which are set elsewhere. You may, however, decide not to use the FirstSpirit mail service by deselecting the respective box on the lower right.

2.4. Quote Configuration

Quote configurations allow controlling when and how pages and datasets registered for translation are processed and when a translation job is actually being initiated.

There are 2 types of configuration available

  1. Default Configuration
  2. Custom Configurations

Importantly, both types do not differ in terms of available options.

The default quote configuration can be used at any time and will also be used in case a previously defined custom quote configuration is removed from this list although there are elements already registered for translation.

You may add unlimited custom quote configurations under the respective tab’s panel.

Default Quote Configuration.
Figure 5. Default Quote Configuration.


The available settings will be described in the following:

  • Configuration Name
    (custom quote only) This name will be used to identify the job within the module.
  • Initiate translation if at least X page(s) require translation
    Set the minimum amount of pages required before a translation is actually initiated. Note: Datasets will be regarded as single pages.
  • Start if oldest element is X day(s) old
    If the oldest element waiting to be translated in FirstSpirit has not been committed for translation after the amount of days specified here, a translation will be initiated regardless of the other criteria above.
  • Start if deadline is reached in X day(s)
    Each translation request might have a date at which the translation is due. Since every translation requires time, this setting allows you to configure the number of days waited before the expected date of completion would be reached and to finally initiate a translation process.
  • Pages per translatable XML file
    Once a job has been processed, this setting determines the amount of time until another job will be processed. The minimum delay can be used to force that a certain amount of time is in between to exports.

A translation will be initiated if at least one of the above criteria is met.

A zero value in Number of pages required or Start if oldest element is X day(s) old deactivates the respective criterion.

A negative value for Start if deadline is reached in X day(s) deactivates the respective criterion.

All changes made will only be stored if you click on the “Apply Changes” button.

2.5. Connectors

Connectors are used to connect to various Translation Memory System (TMS). The following types of connectors are available.

  1. Default Filesystem Connector
  2. Amazon Web Services (AWS) Connector *
  3. DeepL Connector *
  4. Google Translate Connector*
  5. Additional Custom Connectors

Connectors marked with an (*) provide machine translations and the result should be reviewed. There will be no guarantee regarding the correctness of the translations created by any machine translation system.

The Filesystem Connector can only be configured but not removed. It will be used if no particular connector is required.

The AWS, DeepL and Google Translate connectors can only be used if you provide valid credentials and access keys in its respective configuration panel.

Filesystem Connector
Figure 6. Filesystem Connector


Custom connectors require additional configuration and can be added as needed.

You can activate the TranslationHelper plugin by activating the feature in either of these connectors.

If your TranslationStudio is hosted in the cloud, you do not necessarily need AWS credentials. Please contact your administrator for further information.

Custom Connectors
Figure 7. Custom Connectors


The custom connector panel consists of 2 areas:

  1. List - A list of all connectors available to TranslationStudio
  2. Details - Provides details to configure and use the respective system connector

New connectors can be added or removed using the respective icons next to the list and 3 pieces of information are required for each available system in order to work properly:

  1. A name has to be provided which will be used to address this system when referring to it in FirstSpirit
  2. The Configurable entry holds the fully qualified class name which implements the TranslationMemorySystemConnectorConfigurationGui interface from the connector API.
  3. The Connector entry holds the fully qualified class name which implements the TranslationMemoryConnector interface from the connector API.

You can (optionally) load the required data from a connector’s xml file which makes this installation easier. The xml file must follow the xml structure shown below (using data from the above screenshot to provide sample data). You can load the file using the load from file button in the upper right.

<?xml version="1.0" encoding="UTF-8"?>
 <connector>
  <name>Custom Connector</name>
  <configurable>com.mycompany.connector.configuration.Panel</configurable>
  <instance>com.mycompany.connector.instance.Connector</instance>
  <xml-connector></xml-connector>
  <xml-gui></xml-gui>
 </connector>

To configure the respective connector, click on the Configure button. Importantly: All changes made to the connector configuration will have to be confirmed using the Apply Changes button.

Please note: each connector provides a list of available projects. For example, a given TMS might provide specific projects for certain language pairs, e.g. from English to German or from English to French.

Other connectors, such as the filesystem connector only provide one single project. Importantly, each project has a unique id which is used to identify the respective project in the TMS. The list of available projects per connector is forwarded to FirstSpirit and available to projects and language mappings.

Depending on the connector and the underlying Translation Memory System (TMS), some TMS projects might be deleted or removed and, consequently, wont be available to TranslationStudio anymore.

Yet, existing language mappings might still have stored the id of the removed TMS project. Thus, it might be necessary to change these mappings and choose other target TMS projects or to remove the respective language mappings from the FirstSpirit project.

However, if a translation is requested using a language mapping with an invalid TMS project, the element might not be processed. Consequently, make sure that language mappings always use existing TMS projects.

Connecting to Translation Memory Servers

Sometimes, a connection to a Translation Memory Server may fail because the server uses self-signed certificates, for example. In that case, you have to add the certificate to the JDK’s default keystore on the server running the TranslationStudio Application.

2.6. Processing

This section contains several features which may be made available to TranslationStudio or not.

Processing
Figure 8. Processing


  • Normalise translated XMLs
    Sometimes, translated XML files contain structural formatting new lines which may cause problems during the import. This setting allows to remove all structural formatting prior imports.
  • Set the translated flag in FirstSpirit after successful imports
    If you activate this feature, pages and sections will be marked as translated after the successful import.
  • Validation of pages
    You may check if a page exists in FirstSpirtit before it is processed.
  • Guess non-standard uids
    TranslationStudio requires alphanumeric uid names as given by the SiteArchitect. Unfortunately, it is possible to add spaces characters and others. This causes problems when exporting the data to the filesystem (because they are mapped to the standard uid convention). Thus, TranslationStudio will not find it, but it may try and translate those non-standard uids. We strongly urge you to use standard uids, because this may cause data confusion and data loss!
  • XML Format
    TranslationStudio supports various XML formats and you may chose either of them as needed.
  • Database Actions
    TranslationStudio keeps track of all the translation requests and informs the user if a page or section (for example) have already been translated in a given language. Since, over time, the structure and content of a given element may change, such stored translation information may cause confusion or simply be outdated. Therefore, you may choose to remove stored information which is older than a given number of days.
  • Metrics
    TranslationStudio can collect metrics (word count of imported XML files and the pages/sections/datasets affected, number of files) which may be relevant for your company. If you receive a monthly summary by providing an email address (list) here. you have to activate metrics in the Monitor section.

2.7. Monitor

TranslationStudio provides tools to monitor the application and to react to specific situations.

Application Monitoring
Figure 9. Application Monitoring


You may decide how often a check is to be carried out.

TranslationStudio is able to identify if a core process has died unexpectedly (e.g. due to an out of memory error) and to respond to such an event according to the settings provided here.

In addition, you may choose to collect some metrical information. Those information can be accessed using the TranslationStudio Dashboard.

2.8. Distribute

TranslationStudio can be installed automatically whenever you its project component to a FirstSpirit project.

Distribute
Figure 10. Distribute


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.

3. Configuring a FirstSpirit Project

In order to use TranslationStudio in your project, the project component has to be added to the project and the installation script executed.

3.1. Configuring Language Combinations

Usually, you do not want your editors to decide which translation language combination and TMS is to be used. This may result in illegal language combinations.

Therefore, supported combinations have to be created. Thereby, you as administrator define which languages can be used as source languages and which languages will be translated into.

To create a mapping, navigate to the Mappings folder fts_configuration in the Global Content Area and create a new page template using the template fts_gca_mapping as shown below: