Page History

...

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

...

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.

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.

...

/editor/instanttranslateapi/filepretranslate

...

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"}

...

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 .

Code Block

title	Response layout example

{
  "allPretranslatedFiles": {
    "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": {
      "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

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

Name	Type	Info
source	string	Source language (rfc5646)
target	string	Target language (rfc5646)
file	multipart/form-data	The file to translate (or use fileName + fileData as alternative to file). "0" as field name is deprecated and will not be supported in one of the next transalte5 versions. OR (since 7.5.0)
fileName	string	Alternative: file name as POST string
fileData	string	Alternative: file content as POST string
customerId	int	Optional. Override customer. Falls back to user's customer with smallest id.
targetWithResources	string (JSON)	Optional. JSON array specifying per-target-language resource assignments.

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"}

targetWithResources format:                                                                                                                                                                                                                                 
  [                                                                                                                                                                                                                                                           
    {"language": "de", "resources": [123]},
  ]

Each entry has:                                                                                                                                                                                                                                             
  - language (string, required): rfc5646 target language code                                                                                                                                                                                                 
  - resources (array of int, optional): specific language resource IDs to use for that target. Empty array = use all available.

NOTE: for multiple target translations use filepretranslateproject endpoint.

/editor/instanttranslateapi/filepretranslateproject

POST

Name	Type	Info
source	string	Source language (rfc5646)
target	string	Comma-separated list of target languages (rfc5646), e.g. "de,fr,es"
file	multipart/form-data	The file to translate (or use fileName + fileData as alternative to file). "0" as field name is deprecated and will not be supported in one of the next transalte5 versions. OR (since 7.5.0)
fileName	string	Alternative: file name as POST string
fileData	string	Alternative: file content as POST string
customerId	int	Optional. Override customer. Falls back to user's customer with smallest id.
targetWithResources	string (JSON)	Optional. JSON array specifying per-target-language resource assignments.

Starts a project-based file pretranslation that supports multiple target languages. When multiple targets are given, a project with one task per target language is created.

Code Block

language	php

  targetWithResources format:                                                                                                                                                                                                                                 
  [                                                                                                                                                                                                                                                           
    {"language": "de", "resources": [123]},                                                                                                                                                                                                                   
    {"language": "fr", "resources": [456, 789]},                                                                                                                                                                                                              
    {"language": "es", "resources": []}                                                                                                                                                                                                                       
  ]
                                                                                                                                                                                                                                                           
  Each entry has:                                                                                                                                                                                                                                             
  - language (string, required): rfc5646 target language code                                                                                                                                                                                                 
  - resources (array of int, optional): specific language resource IDs to use for that target. Empty array = use all available.                                                                                                                               
                                                                                                                                                                                                                                                              
  Response (single target):                                                                                                                                                                                                                                   
  {"taskId": 539}                                                                                                                                                                                                                                             
                                                                                                                                                                                                                                                              
  Response (multiple targets — project):                                                                                                                                                                                                                      
  {"taskId": 539, "projectTaskIds": [540, 541, 542]}                                                                                                                                                                                                          
  
Where taskId is the project ID and projectTaskIds are the individual task IDs per target language.

/editor/instanttranslateapi/task/{taskId}/sendtohumanrevision

POST

Name	Type	Info
taskId	int	URL path param — the task ID
customerId	int	Optional. Must be one of the user's assigned customers. Falls back to primary.
description	string	Optional. Description for the human revision task.
workflow	string	Optional. Workflow to use.
custom	object	Optional. Additional key-value pairs to set on the task.

Sends a pretranslated file task to human revision workflow.

Success response: {"result": "success"}

/editor/instanttranslateapi/task/{taskId}/edittask

POST

Name	Type	Info
taskId	int	URL path param - the task ID

Opens a file translation task for editing in the translate5 editor. Requires config
runtimeOptions.plugins.InstantTranslate.enableTaskEdit to be enabled.

Response: Redirects to editor/taskid/{taskId}

/editor/instanttranslateapi/task/{taskId}/savetotm

POST

Name	Type	Info
taskId	int	URL path param - the task ID

Saves the edited task segments into the InstantTranslate TM.

Success response: {"result": "success"}

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

Code Block

title	Response layout example

{
  "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.

/editor/instanttranslateapi/filepretranslatenow

(since 7.15.0)

POST

Name	Type	Info
source	string	Source language (rfc5646)
target	string	Target language (rfc5646)
file	multipart/form-data	The file to translate (or use fileName + fileData as alternative to file). "0" as field name is deprecated and will not be supported in one of the next transalte5 versions. OR (since 7.5.0)
fileName	string	Alternative: file name as POST string
fileData	string	Alternative: file content as POST string
customerId	int	Optional. Override customer. Falls back to user's customer with smallest id.
targetWithResources	string (JSON)	Optional. JSON array specifying per-target-language resource assignments.

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

Waits until the import is finished and directly returns the results of the translated task.

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

Response examples: {"taskId":"539","fileTranslation":".."}
{"taskId":"539","error":"Task import timeout exceeded (60s)"}

targetWithResources format:                                                                                                                                                                                                                                 
  [                                                                                                                                                                                                                                                           
    {"language": "de", "resources": [123]},
  ]

Each entry has:                                                                                                                                                                                                                                             
  - language (string, required): rfc5646 target language code                                                                                                                                                                                                 
  - resources (array of int, optional): specific language resource IDs to use for that target. Empty array = use all available.

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:

Code Block

title	Config value

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

runtimeOptions.InstantTranslate.synchronousTranslateTimeout

integer

60

Maximum seconds the synchronous filepretranslatenow endpoint waits before returning a timeout error. Minimum enforced: 6 seconds.

runtimeOptions.plugins.InstantTranslate.enableTaskEdit

boolean

1

If enabled, InstantTranslate users can open and edit file translation tasks in the editor. User also needs the "Editor" role.

runtimeOptions.plugins.InstantTranslate.enableMultiLanguageFileTranslation

boolean

1

If enabled, the UI shows a multi-target-language selector for file translation, enabling the project workflow via filepretranslateproject

...

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

ex:

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

...

When requesting this api endpoint, for the given language combination and for all customers (enabled with config see info bellow) of a users with InstantTranslate right, separate memory will be created and the requested content will be saved there. To enable Instant-Translate memory to be created for customer, this config must be set: runtimeOptions.InstantTranslate.saveToServices

This config is customer specific, and can be configured for each customer separately. By default this feature is disabled.

Configuration of InstantTranslate

If value is selected, instant translate translations will be saved in separate TM of the selected type(s). Currently only OpenTM2 is supported

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	.

Page tree

Versions Compared

Old Version 18

New Version Current

Key

Translate a file with translate5 language resources

Translate a file with translate5 language resources

Auto creation of memory

Configuration of InstantTranslate

Configuration of InstantTranslate