Checking File Translation Status

Once files have been successfully uploaded and the translation process initiated, API integrations may need to check file status to determine whether translations are ready to be downloaded. While callbacks can be used for this purpose, it is recommended to supplement callbacks with a polling mechanism.

Three endpoints are available to check the status of files:

• List recently published files 
• Status of file for each locale
• Status of file for a single locale

The "recently published files" endpoint is particularly useful if you have a large number of files in Smartling, as it helps avoid checking the status of each file individually. 

The other endpoints provide more details on the translation status of the content within a file. The information below provides more details on how to use the data provided by these endpoints.

This formula connects the relevant numbers returned by the "Status of file for a single locale" endpoint:

Count of unauthorized strings = totalStringCount - (authorizedStringCount + completedStringCount + excludedStringCount)

Converting this into a progress number yields:

translation progress = completedStringCount / (completedStringCount + authorizedStringCount)

However, this formula doesn't take into account a couple of use cases:

1. Content submitted without authorization: Integration submitted content without authorization (user is going to review content and authorize it in the dashboard later). In this case, translation progress should be 0%.
2. File submitted with all translations already available but with a few new unauthorized strings: Integration already has all translations, but submitted an updated file with a few new strings AND without authorizing them. This use case is similar to the previous one and might manifest in the integration as source language "bleed through."
3. All strings excluded from translation: Integration submitted content and all strings were excluded from translation in Smartling. It can be the result of a poorly configured integration submitting data that should not be translated. In any case, translation progress should be 100% since all of its content was excluded from translation.

To account for these scenarios, the integration must implement the following formula to evaluate current progress and determine whether to download translations. This formula always respects unauthorized strings: 

if ((total - excluded) == 0) {
    // if nothing is authorized then check special case when everything was excluded

    progress = 100%
} else {
    // Progress takes into account unauthorized + authorized + completed strings
    // So if file has at least one unauthorized string
    // then progress will be always <100%

    progress = completed / (total - excluded)
}

Test Cases

Below are some test cases that can be used to validate this logic. 

"totalStringCount": 10,
"authorizedStringCount": 4,
"completedStringCount": 0,
"excludedStringCount": 1,

progress = 0%, 4 strings are ready for translation but translator didn't start yet
________________________________

"totalStringCount": 10,
"authorizedStringCount": 4,
"completedStringCount": 5,
"excludedStringCount": 1,

progress = 55%, it's common case
________________________________

"totalStringCount": 10,
"authorizedStringCount": 2,
"completedStringCount": 5,
"excludedStringCount": 1,

progress = 55%, 2 strings are waiting for translation and 2 more for authorization
________________________________

"totalStringCount": 10,
"authorizedStringCount": 0,
"completedStringCount": 5,
"excludedStringCount": 1,

progress = 55%, still 4 strings are waiting for decision (authorize/exclude)
________________________________

"totalStringCount": 10,
"authorizedStringCount": 0,
"completedStringCount": 9,
"excludedStringCount": 0,

progress = 90%, file was uploaded without authorization, user will do this later or will add file to job
________________________________

"totalStringCount": 10,
"authorizedStringCount": 0,
"completedStringCount": 0,
"excludedStringCount": 0,

progress = 0%, file was uploaded without authorization, user will do this later or will add file to job.
________________________________

"totalStringCount": 10,
"authorizedStringCount": 0,
"completedStringCount": 0,
"excludedStringCount": 10,

progress = 100%, nothing to translate, user excluded all content
________________________________

"totalStringCount": 1000000,
"authorizedStringCount": 0,
"completedStringCount": 999999,
"excludedStringCount": 0,

progress = 99%, must return 99% even if 99.9999% translated
________________________________

"totalStringCount": 0,
"authorizedStringCount": 0,
"completedStringCount": 10,
"excludedStringCount": 0,

Throw exception, totalStringCount must be greater than 0