Using API to Manage a Translation Project: Part Two

api.text.united.2

APIs could be described as sets of requirements that inform one application on how to talk to another. If you’d want to describe it in a more poetic way, APIs would be little gems that make web-service mash-ups possible. That’s why most large companies have built APIs for their customers and as you probably guessed it, so did Text United!

If it’s the first time you’re reading about it, we officially welcome you to our new blog series for tech-savvy users that explain thoroughly how to use Text United API to manage a Translation Project! We created this series for those, who want to familiarize themselves with our system and become advanced in handling translation projects through it step by step. What you will find in this series are the parts of code along with the description as well as use cases of API Examples to download and work on. Answering your questions straight away: yes, you can copy the code and use it.

The example code is a C# console application created in Visual Studio 2017 by our developers. You can read about the API method it uses here.  The main code of the example is placed in the Main() method of the Program.cs. It includes 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 three short steps that explained what are the helper methods you should be familiar with and which method classes you should know before starting the project. Then, we followed with descriptions on how to add the supported languages and company users to the project.

Today, in the second part, we are about to explain 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.

Are you ready to play with the code?

Step #3: Create a Project with One .resx File for Translation 

In the example, we are translating SampleResourceFile.resx file. The file is included in the solution and will be copied to the bin folder of the application. So you may read it and convert into a Base64 string. The best approach is to open the file as a byte array (do not interpret it, transcode or process in no way). Files for translation must be included in project definition as a list of file objects. In the example it’s a projectSourceFiles list of ApiNewFile objects:

1
2
3
4
5
 byte[] sourceFileContent = File.ReadAllBytes("SampleResourceFile.resx");
string sourceFileBase64 = Convert.ToBase64String(sourceFileContent);
List<ApiNewFile> projectSourceFiles = new List<ApiNewFile>();
projectSourceFiles.Add(new ApiNewFile() { Filename = "SampleResourceFile.resx",
Content = sourceFileBase64 });

As mentioned before, to create a project you will have to set IDs of the source and target languages, and the ID of the translator, as well. Let’s then choose the languages and the translator. In the example below these are EN-US as the source, DE-AT as the target language and the first user as a translator.

1
2
3
ApiSystemLanguage langEnUs = languages.First(l => l.LangCode == "EN-US");
ApiSystemLanguage langDeAt = languages.First(l => l.LangCode == "DE-AT");
ApiUser translator = users.First();

Now, let’s create the project object:

1
2
3
4
5
6
7
8
9
10
ApiNewProject newProject = new ApiNewProject()
{
 ProjectName = "Testing API - 1",
 SourceLanguageId = langEnUs.Id,
 TargetLanguageId = langDeAt.Id,
 TranslatorId = translator.Id,
 Description = "This is a sample project for testing API methods",
 EndDate = DateTime.Now.AddDays(7),
 Files = projectSourceFiles
};

The project is going to start immediately, should be translated in 7 days (that’s only a suggestion to the translator), its name is “Testing API – 1”, languages are EN-US -> DE-AT and the person responsible for translation is John Doe of ID 999995.

See the JSON input object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
"ProjectName": "Testing API - 1",
 "SourceLanguageId": 41,
 "TargetLanguageId": 54,
 "Description": "This is a sample project for testing API methods",
 "EndDate": "2018-06-16T14:52:37.4296732+02:00",
 "Files": [
 {
 "Filename": "SampleResourceFile.resx",
 "Content": "77u/tbD <omitted for brevity> C9yb290Pg=="
 }
 ],
 "TranslatorId": 999995,
 "ProofreaderId": null,
 "InCountryReviewerId": null,
 "ReferenceNumber": null,
 "MachineTranslation": False
}

The project is created after sending the POST request with JSON data to the server. In response an ID of the newly created project is returned. The project ID is saved in projectId variable for the future use.

1
2
3
4
5
6
7
8
WebResponse resNewProject = reqNewProject.GetResponse();
string jsonProjectId = GetResponseJson(resNewProject);
 
Console.WriteLine("\nRaw JSON in response (ID of the newly created project):");
Console.WriteLine(jsonProjectId);
 
string sProjectId = JsonConvert.DeserializeObject<string>(jsonProjectId);
projectId = long.Parse(sProjectId);

Step #4: Get a Collection of Projects to see if it’s ready for Translation

It may take a while for our system to create a project and make it ready for translation. In order to check whether the project is actually ready, you may start polling the list of projects. Knowing the ID of the project look for the appropriate item in the list returned from https://www.textunited.com/api/projects.

‘In progress’ state indicates that the project was kicked off and delivered to translators. In the example code there’s an infinite loop reading the project list in 5 seconds intervals. The loop breaks when there’s a project of the given ID in a state of ‘In progress’.

 

We will explain how to read the project details and project files in Part Three of our series!

Stay Tuned!

 

 

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 *