apps/tools/translatefiles/translate (POST)

Upload a file and have it word counted and pre-translated. Then get back the translated file and word count details.

This method does not require a project.

In most cases, the use of MT Hive should be preferred. MT Hive integrates with the online user interface where translated files can be downloaded and sent into post editing.

URL

(POST) /api/apps/tools/translatefiles/translate

PARAMETERS

Tip: A helper method exists to get some parameters from a project: Word count profile, Document format profile, Project memory and attached resource IDs.

The method is: apps/tools/translatefiles/presets/project/{pid}

The body must contain a JSON object with these properties:

	Original file
fileToken	The token that references the original file to process. Use media/upload to upload your file and to obtain a token.	string, Mandatory
src	Source locale. This is the locale of the original file.	string, Mandatory
trg	Target locale. This is the locale into which to translate.	string, Mandatory

formatId	Optional ID of a specific document format configuration to use. The configuration defines how to extract text from the original file. The system selects a configuration as follows: If formatId is specified: This configuration will be chosen. Otherwise: If formatProfileId is specirfied: The first matching configuration is chosen (based on file extension, name and content). Otherwise: The first matching configuration from all your configurations is chosen. See online at Settings > File formats To enumerate all configurations, see: Document formats	int?, Optional
formatProfileId	Optional ID of a document format profile from which to select a format configuration. Profiles are configured online at Settings > Document format profiles. Tip: Use helper method: apps/tools/translatefiles/presets/project/{pid} To enumerate all profiles, see: Document format profiles

	Translation and word count
wordcountProfileId	Optional word count profile to use. The profile defines how to leverage memories, how to pre-translate from memories, whether to use MT and more. If not set, then the system selects the alphabetically first word count profile configured online at Settings > Word count profiles. Tip: Use helper method: apps/tools/translatefiles/presets/project/{pid} To enumerate word count profiles, see Word count profiles	int?, Optional
resourceIds	Optional list of translation/project memories or term bases to use for leveraging (as well as pre-translation). If not set, then the system will only pre-translate with MT (if a system is enabled in the word count profile) Tip: Use helper method: apps/tools/translatefiles/presets/project/{pid} to get project memory ID and attached resource IDs for a reference project.	int[]?, Optional
disableMT	Optional. Default is false. false: Default. MT is enabled or disabled as per the word count profile. true: MT is disabled always, even if word count profile enabled it	bool?, Optional
copySourceToTarget	Optional. Default is true if not specified. true: Default. Populate untranslated target texts with the original content false: Leave untranslated target texts empty. Avoid use of false with binary files such as Microsoft Word, Excel, Powerpoint, InDesign etc. The system will otherwise very likely fail to build valid translated files.	bool?, Optional
	Results
buildTranslatedFile	Optional. Default is true if not specified. If true then the results will contain a file reference to download the translated file. Use false if you are only interested in the word count information.	bool?, Optional
callbackurl	Optional URL which will be called upon success or failure of operation. This makes polling for results (see below) unnecessary. URL is called as POST request with operation result included in the body, see "RESULTS" chapter below for the JSON format. Suggestion: Include your own references in the URL, example: http://callmeback.mycompany.com?operationid=22222&mydata=abcde	string?, Optional

RESULTS

The operation may take more or less time depending on the amount of data to export. Therefore it is implemented as an asynchronous operation.

The API method returns an Asynchronous operation result:

{
  "trm": {
    "requestid":32230,
    "status":"Waiting",
    "statusText":"Waiting..."
  }
}

If the operation is not completed (status = Finished), you need to poll every few seconds until completion with requestid. When finished you obtain a token to download the JSON file:

{
    "trm": {
        "requestid": 32230,
        "isbatch": false,
        "status": "Finished",
        "statusText": "Finished!"
    },
    "result": { "items": [] },
    "custom": {
        "filetoken": "1104cf62b1934e0f9ae40c43c4af1ae2",
        "segments": 4,
        "texts": 9
    }
}

Get the file: You need to use the call media/get/{token} with token is the custom/filetoken property in the previous result.

JSON FILE FORMAT

The method returns a file. It contains a JSON object with these properties:

key	Segment key	string
format	The content format such as "plain" or "html_1".	string
dt	The last date of change of any property of the segment (texts, status, ...)	datetime
bsid	Sequential number assigned for display in the translation editor. This number may change with push requests.	int
cfs	Segment level custom fields (null if there are none). Each array element has properties id (custom field ID) and v (custom field value)	object[]?
texts	A dictionary of texts. The key is the locale and the value a text object, see below. "texts": { "en": {...}, "fr": {...} }	object[]

EXAMPLES

Basic results without custom fields, labels and comments: