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] }
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" }
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. 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.
| ||||||||||||||||||||||||
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:
|
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.