API - Get translation status

The Beebox proposes automatic, semi-automatic or manual ways in getting files translated. During test and development you will likely want to activate automated "psudeo translation" or "machine translation" workflows, With these workflows source files get immediately translated. With other tests or production you may enable human workflows where it may take hours or days until your source files get translated. From the developer point of view, the actual workflow running behind the curtains remains entirely transparent.

To know when files are translated and ready for download, you need to check the translation status. Either poll the Beebox in regular intervals or check the status upon a user's request.

URL

With a simple filter value, use GET:

(GET) /api/workprogress/translatedfiles?token={token}&filter=&skip=&count=

With a large filter value, please use POST:

(POST) /api/workprogress/translatedfiles

Include parameters as JSON in the request body, e.g. {“token”:…, “filter”:{}}. Make sure to add http header “Content-Type” to “application/json”. Use this version if your filter contains a lot of conditions and the resulting URL would be too large.

PARAMETERS

Parameters are:

{ "targetLocale": "es" }

{ "patterns": { "fpath": "\\.docx?" } }

{ "patterns": { "fpath": "(\\.docx?)|(^marketing\\\\)" } }

Note: Use | and parenthesis to match any of multiple patterns.

{ "filePaths": [ 

   { "Item1": "", "Item2": "myfile.docx" },

   { "Item1": "", "Item2": "subfolder\\myfile2.html" } 

]}

Tip 1 - Performance

For performance reasons, try to filter for the files you are actually interested in. It may be inefficient to get the status for 10.000 files when you only have a single one to look for.

Tip 2 - Pagination

Keep in mind that this method returns a maximum of "count" results (100 by default). If you have a lot of files to enumerate either increase the "count" value or paginate the results by calling the method multiple times (see "skip" parameter above).

RESULTS

The method returns the following JSON.  An HTTP status of 200 indicates success. Other HTTP status values indicate an error.

JSON object per file in the "files" array:

NAVIGATING RESULTS

Iterate the “items” node, an array with one record per translated file and target language.

• Per each record, read the “file” property which is the original file name (including sub directories).
• Per each record, read the “locale” property which is the target language of this translated file.
• Per each record, read the “status” property. If the value is 1, then the file is fully translated and can be downloaded.
• Always check the “total” and “count” properties. If “total” is greater than “count”, then there are more files. You then need to call the method again with the “skip” property set (to go to the second page of results).

USING FILTERS

Always specify a filter that is as restrictive as possible and returns the status of the files you are really interested in.

Example 1 - You group your files into jobs

You use the notion of a job in your system. A job contains one or more files to be translated into one language.

Prefix file names with your job id, such as in "job-200\filexy.xml", "job-200\file33.xml", etc.

In that case you can easily retrieve the status of all job files using regular expressions:

{
	"targetLocale": "es",
	"patterns": { "fpath": "^job-200\\\\" }
}

(Note: "\" must be escaped in JSON as "\\". "\" must also be escaped in regex. Therefore we have 4 backslah to denote a \ in the file name.)

Example 2 - You keep a list of files

You track all files that you have sent but you do not group them. In that case include the list of files to check:

{
	"targetLocale": "es",
	"filePaths": [ 
		{ "Item1": "", "Item2": "job-200\\filexy.xml" }, 
		{ "Item1": "", "Item2": "job-200\\file33.xml" }, 
		{ "Item1": "", "Item2": "pages\\home.html" } 
	]
}

Example 3 - You do not track individual files at all

You do not track the files you send, i.e. you drop files to the Beebox without tracking these actions.

{}

In that case you would not specify a filter (or maybe just the target language).

Retrieve the status of all the translated files. Then read out "tfdate" which is the date when the translated file was created.

Download only those files that have been created after the last time you made this call.

In short: You only need to keep track of the last date of downloading.