Using API to Manage a Translation Project: Part Five

api.pt5

We have created an API like the majority of companies that want to make using their system as effective as possible. But creating an API itself is not enough for everyone to understand the mechanism behind it – that’s why we decided to explain in-depth how to use our API to manage a Translation Project.

In this series, you will find a tutorial on how to manage a translation project step by step along with the parts of the code We made our use cases of API Examples available to download and work on. The example code is a C# console application (feel free to read about the API method it uses here) created in Visual Studio 2017.  The main code of the example is placed in the Main() method of the Program.cs. You will find there all the steps needed to create a project, upload files, check the statuses, generate translated versions and download translations.

In the first part of the series, we presented the helper methods method classes you should know, followed by descriptions on how to add the supported languages and company users to the project. In the second part, we explained how to create a project with one .resx file for translation and get a collection of files to check if it’s ready for translation. In part three, we explained how to read the project details and project files. In the last part, you’ve found out more about the process of translation itself.

Today it’s time for the fifth part that will conclude the whole series, in which you will find out how to check if the translation is ready, download the translated version of the file, and most importantly, update the file in an on-going project.

If you are here for the first time, we encourage you to download the file with use cases, read the previous parts of the series and start familiarizing yourself with our system!

#10. Wait For The Target File To Be Generated

The system needs a few seconds to generate a translated version of the file. So before downloading it, you must check whether the translation is ready. See the code below:

while (true)
{
 Console.Write("Checking... ");
 reqProjectFiles = GetRequest(uriProjectFiles, "GET");
 resProjectFiles = reqProjectFiles.GetResponse();
 jsonProjectFiles = GetResponseJson(resProjectFiles);
 files =
JsonConvert.DeserializeObject<IEnumerable<ApiProjectFile>>(jsonProjectFiles);
 Console.WriteLine("{0}\t{1}\t{2}B\t{3}", files.First().FileId,
files.First().Filename, files.First().FileSize, files.First().Status);
 if (files.First().Status == "Translated") break;
 Thread.Sleep(1000);
} 

It reads the files in a loop with 1-second interval and looks for the status of the first (and only) file. The loop breaks when the Status turns into “Translated”. That means the file can be downloaded.

#11. Download The Translated Version of The File

Download a file by requesting https://www.textunited.com/api/projectfiles with three parameters:

string uriDownload = string.Format(
"https://www.textunited.com/api/projectfiles?projectId={0}&fileId={1}&type=translated"
, projectId, fileId); 

This request sends back a translated version (type=translated) of a file given by fileID from a project defined in projectId. The result is a JSON structure representing file content:

 "Content": "77u/P <omitted for brevity> m9vdD4=",
 "FileId": 1087770,
 "Filename": "SampleResourceFile.de.resx",
 "Subdir": null,
 "FileSize": 6157
} 

That can be then converted into an ApiProjectFileContent object and saved locally on disk. Remember that the content must be first decoded from the Base64 string:

ApiProjectFileContent downloadedFile =
JsonConvert.DeserializeObject<ApiProjectFileContent>(jsonDownload);
byte[] byteContent = Convert.FromBase64String(downloadedFile.Content);
File.WriteAllBytes("translated." + downloadedFile.Filename, byteContent); 

#12. Updating Files in an Ongoing Project

When the project is an in-progress state, you may upload new files or update the existing ones. In order to do this, send a POST request to https://www.textunited.com/api/projectfiles 

The POST content must include:

ProjectId – project ID field

and

Files – a collection of the file objects.

Each file must have the following properties:

Filename – file name string

Content – Base64-encoded content of the file.

See a JSON example for this call:

 {
 "ProjectId": "42217",
 "Files": [
 {
 "Content": "UEsDBBQABgAI … AAAOAA4AhwMAAPxHAQAAAA==",
 "Filename": "UpdateSample.docx"
 }
 ]
}

The request is served asynchronously, which means that you’ll immediately get a boolean response indicating whether it was accepted (true – when accepted). Remember though that the process may take a while.

You’ll see the change in the project after a couple of seconds or minutes, depending on the project size. Please keep in mind, that if there are any files in the update matching the files already included in the project, they will overwrite the existing ones. Any new files will be simply added to the project.

Now you have all the information to start managing a translation project by yourself with our API! Download the use cases here and let the fun begin!

In case you missed it, check out previous entries:
Using API to Manage a Translation Project: Part One
Using API to Manage a Translation Project: Part Two
Using API to Manage a Translation Project: Part Three
Using API to Manage a Translation Project: Part Four

 

Related Posts

Gosia
Written By:

Gosia loves copywriting and product translation. Additionally, she's a content marketing and lolcats junkie.

Add a Comment

Your email address will not be published. Required fields are marked *