BS [i]-flow TMS Connector

About itl

Translations into any language. In any format. Using any established TM tool.

The Institut für technische Literatur has over 35 years of experience translating technical documents: They offer technical translations into any language by expert translators who are native speakers. They use all the established translation memory systems.

Would you like to entrust your urgent ad hoc translations or a large multilingual project to a reliable team of experts who will provide you with high-quality translations in the desired target languages and stick to the agreed deadlines? Would you like to optimize your translation processes using a translation memory system and integrate them as best as possible into your document creation processes? Would you like to localize your content? And would you like to use consistent terminology throughout your company and present a consistent face in your external communications?

Then take advantage of itl’s translation experience, and make it a key factor in your success. Visit the website for more information.

About [i]-flow

The internal itl [i]-flow translation management system reduces project management outlay and controls the data flow. It is the ideal interface between itl and its customers. Orders can be placed and tracked with ease. [i]-flow automates recurring workflows and thus reduces process times. [i]-flow offers a central platform for all those involved in the translation process – from the product manager or writer via the project manager, service provider, and translator to reviewers, DTP specialists, and printers.

Furthermore, [i]-flow is ideal for various system interfaces designed for automated information exchange.

About the BS [i]-flow TMS Connector

The Contentserv TMS module allows for collecting content, for example, from a PIM product and creates translation jobs from it. TMS plugins can then pick up the terms in those translation jobs and exchange them with external translation management solutions.

The BS [i]-flow TMS Connector connects the Contentserv TMS via the [i]-flow interface with the itl platform. It can export any translation job from Contentserv to [i]-flow via a REST API. The actual translations are then performed on the itl platform. Completed translations are imported back to Contentserv, and subsequent Workflow Actions can be triggered automatically.

Together, the Contentserv TMS and the BS [i]-flow TMS Connector allow for building a sophisticated end-to-end translation pipeline.

Architecture

Exporting Translation Jobs (Manually and via Active Script)

When the export of a translation job is triggered, the Contentserv translation memory data is extracted and packed in JSON format that contains all data for translation. The translation job is then submitted via REST API. In case of success, the state of the translation job in [i]-flow changes to “Created” (see status overview table).

Cancelling Translation Jobs

The architecture also allows for canceling sent translation jobs. Not all translation jobs can be canceled, though; this depends on their state in [i]-flow (E.g., translations that have already been started cannot be canceled).

Importing finished translations (Manually and via Active Script)

The connector can query the state of the sent jobs via REST API (and display them with the individual translation jobs in Contentserv). Finished translations can be imported back to the Contenserv TMS. The import can be triggered manually by pressing the import button for individual translation jobs. It can be automated with an Active Script that imports all finished translations for all translation jobs. The script can be configured to run on a scheduled basis (e.g., every 10 minutes). One JSON file with the translated content is imported for each language for each job. When the import was successful, the connector writes the translations to the Contentserv translation memory as expected. Subsequent workflow actions are triggered when the whole translation job is completed its state changes to finished.

Adopting the connector to a new project

Currently, the connector has some features that are very tailored to specific use-cases. If you are planning on adopting the connector, please get in touch so that we can generalize those features to make sure that all your use cases are covered.

Installation & Licensing

For general information on the installation of Business Solution modules, you can refer to https://contentserv.atlassian.net/wiki/spaces/DOCU/pages/1209172593 and https://contentserv.atlassian.net/wiki/spaces/DOCU/pages/2148663314.

You can also check out the module from SVN to install it outside of the Contentserv Cloud:

As a prerequisite, you have to install the alani module from the Subversion repository:

CS Version

SVN Branch

Then the connector module can be checked out:

CS Version

SVN Branch

Configuration

Activating the License

Make sure the license for the BS [i]-flow Connector is activated in Settings → BS → License:

Basic configuration

The connector's basic configuration can be set up in Settings → BS → [i]-flow Connector.

Setting

Function

Setting

Function

API Key

API Key for the [i]-flow API. Must be provided by itl.

Company ID

Company ID for to be used with the [i]-flow API. Must be provided by itl.

Server URL

The API endpoint. Must be provided by it. The connection status is indicated below and will change to connected if the credentials are valid, and a connection with the [i]-flow backend could be established.

User for Context Document

When a URL to a Smart Document is sent as context information with items, an authorization PIN is used so that the translator can access the documents without a log-in to Contentserv. The permissions that are granted by that PIN are those of the user that is selected here. A description of the required permissions is given below.

Debug Mode

If this option is checked, additional entries are written to the log files. It should only be activated for debugging purposes. In a normal production setup, this option should not be checked.

User Rights for the Context Document

In general, no particular rights are required to render the Smart Documents when they are requested by a translator. However, each Smart Template may require specific rights or use APIs requiring additional rights.

If you don’t know which rights are required, you could first try if the rights of the “Anonymus“ user work with your Smart Documents. If additional rights are required you may have to use another user or create one that is provided with the particular rights.

For instance, in our testing environment, it was required to add the rights to view MAM files.

Tip: You can see the exact context URLs that are sent to [i]-flow when you switch on the debug mode in the global connector settings. Then you can find the “context“ node with the URL in the JSON that is sent as a POST request in the connector logs. In a new browser session, you can then test if you can access the context document.

Translation Manager

The Connector has to be added to the list of active Export Plugins in Settings → BPM → Translation Manager.

Integration with the Contentserv Translation Manager

The connector integrates into the Automatic Export drop-down in the Export tab of TMS jobs:

Restrictions

Currently, there are the following restrictions for exporting translations:

  • Only product data can be translated

  • An order must only contain one target language

  • A translated product must at least have two parants in the PIM tree and the “hierarchy levels” must be configured in the export

Those restrictions exist because of the development of the connector with specific use-cases in mind. If you are planning on adopting the connector for your project, please get in contact, so that we can eliminate those requirements if necessary.

Export Configuration

Setting

Function

Setting

Function

New state of the imported entries

Defines to which state the reimported terms should be set. This setting is not specific to the connector. For instance, setting completed translations to “confirmation required” allows you to set up an approval process in Contentserv. This could be further refined with Workflow Actions and can be integrated with a Dashboard.

Ready for submission

This checkbox marks translation jobs that will be automatically exported (see “Submitting Translation Jobs with a scheduled background job”)

Include parent labels from hierarchy level *

Required. The labels of parent elements are included in the meta-data that is sent to i-flow. Level 1 is the first folder under “Product” in the PIM.

Number of hierarchy levels *

Required. Must be at least 2. The number of levels to include (see setting above).

Smart Preset (optional)

For items (products, channels, MAM-files), a Smart Preset can be selected. A URL pointing to the Smart Document (e.g., a datasheet or catalog page) in the source language will then be sent with each product. The Smart Document can be used as context information by the translator.

The following options are available: “None, “Default Smart Preset” (the default Smart Preset set for the item), or a specific Smart Preset available for the item type.

Note: An authorization PIN is attached to the URL so that translators don’t need Contentserv credentials to access the documents. The permissions granted by the PIN are those of the user selected in the global settings of the connector.

Note: The Smart Document URLs must be accessible via the Internet (TCP / IP).

Workflow Actions (optional)

Workflow Actions that will be performed automatically after the translation is finished. Note: Completed translations will be imported back to the Contentserv TMS on a per-language level. Also, the Workflow Actions are executed once for each item, and each language translated. This option is only available for items (products, channels, MAM-files).

Source language and target language(s) don’t have to be defined in the connector settings. The connector can use the languages that are set in the TMS job.

Templates

You can create new translation jobs from a template that pre-sets parts of the configuration. This is not specific to the connector's functionality and can be done with all translation jobs in Contentserv.

Submitting Translation Jobs manually

After all required configurations are finished, the translation job data can be exported to [i]-flow by clicking the export button.

After the job has been exported, the export button is removed from the editor. The state of the Order will show up in a new section below the Export Configuration:

Submitting Translation Jobs with a scheduled background job

This module ships with the BS iflow Export Active Script Plugin.

Each time this Active Script runs, it will automatically export all TMS jobs with the “Ready for submission” option checked in the [i]-flow export configuration. If the export is successful, the checkbox will be unchecked. A new Order will be created. All TMS jobs are added to that Order. This means that each TMS job of that export will have the same OrderID, but a different ContentID. When all TMS Jobs are included in the Order, the Order is started.

The script can be started manually, but you can also automate the script to run on a scheduled basis (e.g., every 10 minutes).

The Active Jobs logs provide information about the exported translations (see “Log Files & Error Handling“).

Canceling an Order

An Order can be canceled by clicking the Cancel Order button in the export tab. An Order can only be canceled if the translation process has not yet started. You will be informed whether the cancellation was successful or not.

Note: When an Order is canceled, it is canceled for all TMS Jobs in that Order.

Importing completed translations manually.

Completed translations can be imported back to the Contentserv TMS on a per-language level by clicking the import button. The defined Workflow Actions for items are then triggered automatically.

Importing completed translations automatically with a scheduled background job

This module ships with the BS iflow Import Active Script Plugin.

Each time this Active Script runs, it will query for completed translations and import them to the Contentserv TMS. Completed translations are imported on a per-language level. Also, subsequent Workflow Actions for items are executed on a per-language level.

The script can be started manually, but you can also automate the script to import translations on a scheduled basis (e.g., every 10 minutes).

The Active Jobs logs provide information about the imported translations (see “Log Files & Error Handling“).

List view of Translation Status

The list view of translation jobs shows the translation status in [i-flow] in a separate column. This new column is not filterable and searchable. Other fields in the list that are normally filterable and sortable remain filterable and sortable.

Note: To see the new column, you have to add it in the list settings.

A mass action for the list allows for mass-importing and exporting TMS from the list.

Log Files & Error Handling

Connector Log

The path for the log connector log files is [Projekt]/data/logs/processes/bs/iflow/[YEAR]/[YEAR+MONTH]/[YEAR+MONTH+DAY].log

They can also be accessed via UI under BS → iflow → …

Normally only problems with the connector are logged. If debug mode is activated, extended log files are written (e.g., all GET and POST requests and responses in the communication with the API).

BS iflow Import Active Job Log

The log of the Active Job provides information about the imported translation. It is possible to filter the log for warnings and errors that would indicate that there might be an issue that requires attention.

If Debug Mode is activated, extended information is logged.

Technical Details

[i]-flow translation job status overview

The possible states are:

State

Description

Created

This is the initial status after a TMS job has been exported to [i]-flow

In progress

The translation process is in progress.

In review

The translation is being reviewed.

Ready for retrieval

The translation process is complete and can be imported back into Contentserv.

Received

The translation was imported back to Contentserv.

Canceled

Job

( Pending )

Not a state in [i]-flow. Shown in the list of TMS jobs when an [i]-flow Export is configured and not yet marked as “Ready for Submission“

( Ready for Submission )

Not a state in [i]-flow. Shown in the list of TMS jobs when an [i]-flow Export is configured and set as “Ready for Submission“

Locales

In communication with the API, languages are identified by their LCID / ISO Code. Each language in Contentserv is mapped to one of those identifiers. Currently, the following list of languages is supported:

LC

LCN

LCID

Afrikaans - South Africa

af-ZA

1078

Albanian - Albania

sq-AL

1052

Alsatian - France

gsw-FR

1156

Amharic - Ethiopia

am-ET

1118

Arabic - Algeria

ar-DZ

5121

Arabic - Bahrain

ar-BH

15361

Arabic - Egypt

ar-EG

3073

Arabic - Iraq

ar-IQ

2049

Arabic - Jordan

ar-JO

11265

Arabic - Kuwait

ar-KW

13313

Arabic - Lebanon

ar-LB

12289

Arabic - Libya

ar-LY

4097

Arabic - Morocco

ar-MA

6145

Arabic - Oman

ar-OM

8193

Arabic - Qatar

ar-QA

16385

Arabic - Saudi Arabia

ar-SA

1025

Arabic - Syria

ar-SY

10241

Arabic - Tunisia

ar-TN

7169

Arabic - U.A.E.

ar-AE

14337

Arabic - Yemen

ar-YE

9217

Armenian - Armenia

hy-AM

1067

Assamese - India

as-IN

1101

Azeri (Cyrillic) - Azerbaijan

az-Cyrl-AZ

2092

Azeri (Latin) - Azerbaijan

az-Latn-AZ

1068

Bangla - Bangladesh

bn-IN

1093

Bangla - Bangladesh

bn-BD

2117

Bashkir - Russia

ba-RU

1133

Basque - Basque

eu-ES

1069

Belarusian - Belarus

be-BY

1059

Bosnian (Cyrillic) - Bosnia and Herzegovina

bs-Cyrl-BA

8218

Bosnian (Latin) - Bosnia and Herzegovina

bs-Latn-BA

5146

Breton - France

br-FR

1150

Bulgarian - Bulgaria

bg-BG

1026

Catalan - Spain

ca-ES

1027

Central Atlas Tamazight (Tifinagh) - Morocco

tzm-Tfng-MA

4191

Central Kurdish - Iraq

ku-Arab-IQ

1170

Cherokee - Cherokee

chr-Cher-US

1116

Chinese - Hong Kong SAR

zh-HK

3076

(Across) Chinese (Traditional, Hong Kong)

zh-HK

3840

Chinese - Macao SAR

zh-MO

5124

(Across) Chinese (Traditional, Macau)

zh-HK

3840

Chinese - Simplified

zh-CHS

4

(Across) Chinese (Simplified)

zh-CHS-SF

34640

Chinese - Singapore

zh-SG

4100

(Across) Chinese (Traditional, Singapore)

zh-SG

3920

Chinese - Traditional

zh-CHT

31748

(Across) Chinese (Traditional, China)

zh-CN

2896

Chinese (Simplified) - China

zh-CN

2052

(Across) Chinese (Simplified) - China

zh-CN

1872

Chinese (Traditional) - Taiwan

zh-TW

1028

(Across) Chinese (Traditional, Taiwan)

zh-TW

2816

Corsican - France

co-FR

1155

Croatian - Croatia

hr-HR

1050

Croatian (Latin) - Bosnia and Herzegovina

hr-BA

4122

Czech - Czech Republic

cs-CZ

1029

Danish - Denmark

da-DK

1030

Dari - Afghanistan

prs-AF

1164

Divehi - Maldives

dv-MV

1125

Dutch - Belgium

nl-BE

2067

Dutch - Netherlands

nl-NL

1043

English - Australia

en-AU

3081

English - Belize

en-BZ

10249

English - Canada

en-CA

4105

English - Caribbean

en-029

9225

English - India

en-IN

16393

English - Ireland

en-IE

6153

English - Jamaica

en-JM

8201

English - Malaysia

en-MY

17417

English - New Zealand

en-NZ

5129

English - Philippines

en-PH

13321

English - Singapore

en-SG

18441

English - South Africa

en-ZA

7177

English - Trinidad and Tobago

en-TT

11273

English - United Kingdom

en-GB

2057

English - United States

en-US

1033

English - Zimbabwe

en-ZW

12297

Estonian - Estonia

et-EE

1061

Faroese - Faroe Islands

fo-FO

1080

Filipino - Philippines

fil-PH

1124

Finnish - Finland

fi-FI

1035

French - Belgium

fr-BE

2060

French - Canada

fr-CA

3084

French - France

fr-FR

1036

French - Luxembourg

fr-LU

5132

French - Monaco

fr-MC

6156

French - Switzerland

fr-CH

4108

Frisian - Netherlands

fy-NL

1122

Galician - Spain

gl-ES

1110

Georgian - Georgia

ka-GE

1079

German - Austria

de-AT

3079

German - Germany

de-DE

1031

German - Liechtenstein

de-LI

5127

German - Luxembourg

de-LU

4103

German - Switzerland

de-CH

2055

Greek - Greece

el-GR

1032

Greenlandic - Greenland

kl-GL

1135

Gujarati - India

gu-IN

1095

Hausa - Nigeria

ha-Latn-NG

1128

Hawiian - United States

haw-US

1141

Hebrew - Israel

he-IL

1037

Hindi - India

hi-IN

1081

Hungarian - Hungary

hu-HU

1038

Icelandic - Iceland

is-IS

1039

Igbo - Nigeria

ig-NG

1136

Indonesian - Indonesia

id-ID

1057

Inuktitut (Canadian_Syllabics) - Canada

iu-Cans-CA

1117

Inuktitut (Latin) - Canada

iu-Latn-CA

2141

Irish - Ireland

ga-IE

2108

Italian - Italy

it-IT

1040

Italian - Switzerland

it-CH

2064

Japanese - Japan

ja-JP

1041

Kannada - India

kn-IN

1099

Kazakh - Kazakhstan

kk-KZ

1087

Khmer - Cambodia

km-KH

1107

K'iche - Guatemala

qut-GT

1158

Kinyarwanda - Rwanda

rw-RW

1159

Konkani - India

kok-IN

1111

Korean - Korea

ko-KR

1042

Kyrgyz - Kyrgyzstan

ky-KG

1088

Lao - Lao PDR

lo-LA

1108

Latvian - Latvia

lv-LV

1062

Lithuanian - Lithuanian

lt-LT

1063

Lower Sorbian - Germany

dsb-DE

2094

Luxembourgish - Luxembourg

lb-LU

1134

Macedonian - Macedonia

mk-MK

1071

Malay - Brunei Darassalam

ms-BN

2110

Malay - Malaysia

ms-MY

1086

Malayalam - India

ml-IN

1100

Maltese - Malta

mt-MT

1082

Maori - New Zealand

mi-NZ

1153

Mapudungun - Chile

arn-CL

1146

Marathi - India

mr-IN

1102

Mohawk - Canada

moh-CA

1148

Mongolian (Cyrillic) - Mongolia

mn-MN

1104

Mongolian (Mong) - Mongolia

mn-Mong-CN

2128

Nepali - Nepal

ne-NP

1121

Norwegian (Bokmål) - Norway

nb-NO

1044

Norwegian (Nynorsk) - Norway

nn-NO

2068

Occitan - France

oc-FR

1154

Oriya - India

or-IN

1096

Pashto - Afghanistan

ps-AF

1123

Persian - Iran

fa-IR

1065

Polish - Poland

pl-PL

1045

Portuguese - Brazil

pt-BR

1046

Portuguese - Portugal

pt-PT

2070

Pular - Senegal

ff-Latn-SN

2151

Punjabi - India

pa-IN

1094

Punjabi - Pakistan

pa-Arab-PK

2118

Quechua - Bolivia

quz-BO

1131

Quechua - Ecuador

quz-EC

2155

Quechua - Peru

quz-PE

3179

Romanian - Romania

ro-RO

1048

Romansh - Switzerland

rm-CH

1047

Russian - Russia

ru-RU

1049

Sakha - Russia

sah-RU

1157

Sami (Inari) - Finland

smn-FI

9275

Sami (Lule) - Norway

smj-NO

4155

Sami (Lule) - Sweden

smj-SE

5179

Sami (Northern) - Finland

se-FI

3131

Sami (Northern) - Norway

se-NO

1083

Sami (Northern) - Sweden

se-SE

2107

Sami (Skolt) - Finland

sms-FI

8251

Sami (Southern) - Norway

sma-NO

6203

Sami (Southern) - Sweden

sma-SE

7227

Sanskrit - India

sa-IN

1103

Scottish Gaelic - United Kingdom

gd-GB

1169

Serbian (Cyrillic) - Bosnia and Herzegovina

sr-Cyrl-BA

7194

Serbian (Cyrillic) - Montenegro

sr-Cyrl-ME

12314

Serbian (Cyrillic) - Serbia

sr-Cyrl-RS

10266

Serbian (Cyrillic) - Serbia and Montenegro

sr-Cyrl-CS

3098

(Across) Serbian (Cyrillic) - Serbia and Montenegro

sr-Cyrl-CS

1618

Serbian (Latin) - Bosnia and Herzegovina

sr-Latn-BA

6170

Serbian (Latin) - Montenegro

sr-Latn-ME

11290

Serbian (Latin) - Serbia

sr-Latn-RS

9242

Serbian (Latin) - Serbia and Montenegro

sr-Latn-CS

2074

(Across) Serbian (Latin) - Serbia and Montenegro

sr-Latn-CS

1617

Sesotho sa Leboa - South Africa

nso-ZA

1132

Setswana / Tswana - Botswana

tn-BW

2098

Setswana / Tswana - South Africa

tn-ZA

1074

Sindhi - Pakistan

sd-Arab-PK

2137

Sinhala - Sri Lanka

si-LK

1115

Slovak - Slovakia

sk-SK

1051

Slovenian - Slovenia

sl-SI

1060

Spanish - Argentina

es-AR

11274

Spanish - Bolivia

es-BO

16394

Spanish - Chile

es-CL

13322

Spanish - Colombia

es-CO

9226

Spanish - Costa Rica

es-CR

5130

Spanish - Dominican Republic

es-DO

7178

Spanish - Ecuador

es-EC

12298

Spanish - El Salvador

es-SV

17418

Spanish - Guatemala

es-GT

4106

Spanish - Honduras

es-HN

18442

Spanish - Mexico

es-MX

2058

Spanish - Nicaragua

es-NI

19466

Spanish - Panama

es-PA

6154

Spanish - Paraguay

es-PY

15370

Spanish - Peru

es-PE

10250

Spanish - Puerto Rico

es-PR

20490

Spanish - Spain

es-ES_tradnl

1034

Spanish - Spain

es-ES

3082

Spanish - United States

es-US

21514

Spanish - Uruguay

es-UY

14346

Spanish - Venezuela

es-VE

8202

Swahili - Kenya

sw-KE

1089

Swedish - Finland

sv-FI

2077

Swedish - Sweden

sv-SE

1053

Syriac - Syria

syr-SY

1114

Tajik (Cyrillic) - Tajikistan

tg-Cyrl-TJ

1064

Tamazight (Latin) - Algeria

tzm-Latn-DZ

2143

Tamil - India

ta-IN

1097

Tamil - Sri Lanka

ta-LK

2121

Tatar - Russia

tt-RU

1092

Telugu - India

te-IN

1098

Thai - Thailand

th-TH

1054

Tibetan - China

bo-CN

1105

Tigrinya - Eritrea

ti-ER

2163

Tigrinya - Ethiopia

ti-ET

1139

Turkish - Turkey

tr-TR

1055

Turkmen - Turkmenistan

tk-TM

1090

Ukrainian - Ukraine

uk-UA

1058

Upper Sorbian - Germany

hsb-DE

1070

Urdu - (reserved)

ur-IN

2080

Urdu - Pakistan

ur-PK

1056

Uyghur - China

ug-CN

1152

Uzbek (Cyrillic) - Uzbekistan

uz-Cyrl-UZ

2115

(Across) Uzbek (Cyrillic) - Uzbekistan

uz-UZ-Cyrl

1620

Uzbek (Latin) - Uzbekistan

uz-Latn-UZ

1091

(Across) Uzbek (Latin) - Uzbekistan

uz-UZ-Latn

1619

Valencian - Valencia

ca-ES-valencia

2051

Vietnamese - Vietnam

vi-VN

1066

Welsh - United Kingdom

cy-GB

1106

Wolof - Senegal

wo-SN

1160

Xhosa - South Africa

xh-ZA

1076

Yi - China

ii-CN

1144

Yoruba - Nigeria

yo-NG

1130

Zulu - South Africa

zu-ZA

1077