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:

token	The session token obtained when connecting.
filter	An optional JSON string. If omitted this the method enumerates all translated files in all target languages. Find status for a specific target language { "targetLocale": "es" } If you do not specify the language the result will return one record per project target language and per file. Find status for all files matching a regular expression: { "patterns": { "fpath": "\\.docx?" } } Note: "\" must be escaped in JSON using "\\". { "patterns": { "fpath": "(\\.docx?)\|(^marketing\\\\)" } } Note: Use \| and parenthesis to match any of multiple patterns. Find status for a list of specific files: { "filePaths": [ { "Item1": "", "Item2": "myfile.docx" }, { "Item1": "", "Item2": "subfolder\\myfile2.html" } ]} This retrieves the status of two files (“Item2”) by their name. “Item1” must be set to an empty string, always. Find status by specific status: { "tmsstatus": [6,7] } `tmsstatus` (array of integers): A list of status values to filter by. This retrieves the status of files based on specified status values. Only files with the provided status values will be returned. find below the list of available status values Find status by specific source file date and target file date: { "sfdate": "2024-01-01", "tfdate": "2024-01-07" } `sfdate` (string): The source file date to filter by (YYYY-MM-DD format). `tfdate` (string): The target file date to filter by (YYYY-MM-DD format). This retrieves the status of files based on specific source file dates and target file dates. Only files with source file dates on or after the specified date and target file dates on or after the specified date will be returned. Sorting Options The `sortOptions` parameter allows you to define the order in which the results are returned. It accepts an array of sorting criteria, each specifying a field and the direction of sorting. PLEASE NOTE: Avoid this option if your Beebox project contains more than a few hundred files. Enumerating and sorting many files will be slow. Parameters: `field(string)`: The field by which to sort the results. Supported fields include: `sfdate`: Source file date `tfdate`: Target file date `dir` (string): The direction of sorting. Possible values are: `asc`: Ascending order `desc`: Descending order Example: { "sortOptions": [{ "field": "sfdate", "dir": "asc"}, { "field": "tfdate", "dir": "desc"}] } this will sort the results by `sfdate` ascending then by `tfdate` descending. More filters You can combine the different filter properties into a single JSON. There are many more filter options and these are described in the online documentation.
skip	Optional number, default is 0. Used for pagination. The files to skip.
count	Optional number, default is 100. Used for pagination and indicates the total number of files to return from this call. Make sure to specify a limit corresponding to your page size (e.g. 100).

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.

skip	Total items skipped (see URL parameter).
count	Total items returned by the method.
total	Grand total items. "total" will be identical to "count" if no pagination takes place. If this number is bigger than “count”, you need to issue the API method again to get more results (with the “skip” parameter set in order to show the second page etc).
files	Json array containing the summary totals individually per language. Each array element is a JSON object with the structure described in table below.

JSON object per file in the "files" array:

file

Relative file path.

locale

The target language code.

uptodate

Boolean. True if the file is translated and ready for download. You can now proceed with a download.

localename

The target language name.

segments

Total segments.

words

Total words.

folder

Folder name. Always an empty string.

status & statusc

Detailed status information: status is a numeric value and statusc is a string.

"status"	"statusc"	Comments
1	Uptodate	File translated and ready to download. Same as when uptodate field is true.
4	New	Pass-through projects only. See PT - Translation Workflow
5	Submitting	Pass-through projects only.
6	InProgress	Translation workflow in progress
7	Done	Translation finished but not yet downloadable.
8	Error	Pass-through projects only.
10	Cancelled	Translation workflow cancelled.

sfdate

Source file date, as shown in the Beebox "in" directory.

sfdatemin

Minutes since the source file was saved to Beebox.

tfdate

Deliverable file date. The date when the deliverable (translated file) was created.

tdate

Minutes since the deliverable file date.

Regular and CMS projects only:

readyToBuild

Boolean. True if translation finished but not yet downloadable. Same as status = 7.

notReadyToBuild

Boolean. True if translation is in progress. Same as status = 6.

Pass-through projects only:

tms

Advanced workflow information. A JSON object with these properties:

error: Last workflow error text.
info: Last workflow info text.
pfdt: Date when preliminary file was downloaded. If not null then preliminary file available for download.
Note: There are more undocumented properties. Ask Wordbee.

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.