View Source

If the API changes in an incompatible manner this is listed explicitly in the "important release notes" section of each releases changelog.

Description

InstantTranslate is translate5 api interface which can be used for translating text and files using the translate5 language resources (term collections, translation memories or machine translation engines).

Available language resource for InstantTranslate are the assigned resources of a customers of the current logged-in user.

For translating files, the file-extension must be configured accordingly.

Translate text with translate5 language resources .

URL:	/editor/instanttranslateapi/translate
Available Methods:	POST
Specialities:	To be able to search for a text, there must be available language resources assigned to a customers of a user
Availability:	-

Translate text resource Layout

Name	Type	Info
text	string	The string to translate.
source	string	The source language to translate from. Must be valid rfc5646 code.
target	string	The target language to translate to. Must be valid rfc5646 code.
langresType	string	optional, one (or more, comma-seperated) language-resource types. e.g. "DeepL" or "DeepL,Google" The types can be ('TermCollection', 'NEC-TM', 'OpenTM2', 'DeepL', 'SDLLanguageCloud', 'GroupShare', 'Google', 'Moses', 'Lucy LT', 'TildeMT')
langresId	int	optional, one (or more, comma-seperated) language-resource id's, e.g "12345" or "12345,23456"
nosegmentation	int	optional, if set to "1" the string to translate will not be segmented (even if it contains punctuation). Please note, the result-layout with segmented & unsegmented texts is different
escape	int	optional, if set to "1" the returned texts and any markup will be escaped

Translate a file with translate5 language resources

Please ensure that:

the filetype is supported (e.g. by Okapi) and
LanguageResources for the desired language-combination are available (order of their application: first termCollections, second TMs, third MTs).

Translating files can take a while.

URL

Methods

Parameters

Description

/editor/instanttranslateapi/filepretranslate

POST

file: multipart/form-data; the file to translate. "0" as field name is deprecated and will not be supported in one of the next transalte5 versions.

source: string; the source language to translate from. Must be valid rfc5646 code.

target: string; the target language to translate to. Must be valid rfc5646 code.

Step 1: Starts a task-import with the file and its pretranslation.

As long as the import is running, the response in step 2 for this file will say "isImporting" instead of returning the download-link. You might need to repeat step 2 until you get the link.

The translated files are available until their configured lifetime is over; then they will be removed automatically.

Response (example): {"taskId":"539"}

/editor/instanttranslateapi/filelist

GET

Step 2: Get a list of all pretranslations that are currently available for the InstantTranslate-user including their downloadUrl.

Response: allPretranslatedFiles for tasks with taskId as key .

{
  "allPretranslatedFiles": {
    "2237": {
	  "taskId":"2237",
      "taskName": "Apache short-en-de.html",
      "sourceLang": "en",
      "targetLang": "de",
      "downloadUrl": "/editor/task/export/id/2237?format=filetranslation",
      "removeDate": "2021-03-18",
      "importProgress": []
    }
    "2464": {
 	  "taskId":"2464", 
      "taskName": "Single word-de-en.html",
      "sourceLang": "de",
      "targetLang": "en",
      "downloadUrl": "isImporting",
      "removeDate": "2021-04-08",
      "importProgress": {
        "progress": 2, // import percentage
        "workersDone": 1, // total workers done
        "workersTotal": 9, // total queued workers
        "taskGuid": "{a5945d9f-4007-4063-ac17-41da3003dab1}",
        "workerRunning": "editor_Plugins_Okapi_Worker"
      }
    }
  },
  "dateAsOf": "2021-04-06 17:36:42"
}

downloadUrl: 'isImporting' | 'isErroneous' | 'isNotPretranslated' | url (the url starts a common task-export; the translated file is included in the exported ZIP)
importProgress: check Task importprogress api

editor/instanttranslateapi/writetm

POST

The request parameters must be encapsulated in data parameter as json.

ex:

data={"sourceLanguage": "en","targetLanguage": "de","source": "Simple text","target": "Einfacher Text"}

An example call via CURL could look like this:

curl --location --request POST

'http://t5docker.localdev/editor/instanttranslateapi/writetm' \
--header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
--header 'Accept: application/json' \
--header 'Translate5AuthToken: {{token}}' \
--form 'data="{\"sourceLanguage\": \"en\",\"targetLanguage\": \"de\",

\"source\": \"Simple text hello\",\"target\": \"Einfacher Text hallo\"}"'

Auto creation of memory

For each customer and language and language combination provided in the request(see example on the left), one memory will be auto created. And the source and the target content will be saved in those memories.

Which customers will be used? The assigned customers to all users, not the current user which is making the request, but all available users in translate5 with instantTranslate role.

With the runtimeOptions.InstantTranslate.saveToServices (overwrite on client level) it can be defined which TM memory resources can be used. By default this is disabled on instance level. Currently only available options are t5memory.

Configuration of InstantTranslate

runtimeOptions.LanguageResources.searchCharacterLimit

map

Maximum character per language resource allowed for search. The configuration key is the language resource id, and the value is the character limit. Ex: {{"1": 100},{"2": 300}}

runtimeOptions.InstantTranslate.pretranslationTaskLifetimeDays

int

2

How many days do you want to keep pretranslated files before the system removes them?

runtimeOptions.InstantTranslate.saveToServices

string

If value other than "disabled" is selected, instantTranslate translations can be saved in separate TM of the selected type(s) by calling editor/instanttranslateapi/writetm. Currently only OpenTM2 is supported.

runtimeOptions.InstantTranslate.user.defaultLanguages

map

1

Default search languages for instant-translate which will be pre-selected when instant-translate is loaded.

Example how to configure the config:

{
 "sourceLangDefault": "en", 
 "targetLangDefault": "de"
}