Using API to manage a translation project
The example code is a C# console application created in Visual Studio 2017. It uses API methods described at https://www.textunited.com/translation-api. 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 file(s), check their statuses, generate translated versions and download translations.
1. Helper methods and model classes
Some repetitive operations performed in most of the steps are defined in a form of helper methods that are described below.
WebRequest GetRequest(string uri, string httpMethod)
The helper method that accepts URI of the API method (with all the parameters, if needed) and the HTTP request method (i.e. GET, PUT, POST, DELETE). It returns a WebRequest object that may be used to get a response from the server. The request object includes credentials needed to authenticate and authorize the call. See authCompanyId and authApiKey constants defined in a Program class. They are used in the GetRequest() method to identify a caller. Get your Company ID and API Key from a Text United portal (after you login into a corporate account).
WebRequest GetPostRequest(string uri, object modelToPost, out string jsonToPost)
A POST version of the GetRequest() method. It allows you to create a web request object with a JSON structure inside. The JSON string is built from the modelToPost parameter passed to the method. When calling an API’s POST method that requires passing an input data, simply create a model class representing the input data structure and pass it as the second parameter to the method.
For debugging purposes the method accepts additionally an output parameter jsonToPost. Use it to see the raw JSON string included by the method in the request object.
string GetResponseJson(WebResponse response)
A method that extracts JSON data retrieved in a response from the server. Pass the WebResponse object as a parameter to the method. The result is a JSON string representing a result from the server.
In order to facilitate processing of the data being sent back and forth between the application and the server, use model classes that represent data structures returned from the server or passed to the server in a form of the JSON strings.
Using model classes makes it easier to convert JSON strings into objects and vice-versa. All the model classes used in the example are located in a Model folder of the project.
Here is the list of them:
- ApiNewFile – an object that represents a source file that can be uploaded to the project. It includes the name of the file and its content.
- ApiNewProject – an object that represents a project to be created. Contains all the data needed to create a project, notably its name, source and target languages, collection of source files and a translator ID.
- ApiProject – an object that represents a project in a list of all projects created by the company in Text United cloud. Properties of the most importance are: project ID, name, state and progress.
- ApiProjectDetails – a detailed information about the project including a collection of files, project team (translators, proofreaders, etc.), analysis, as well as translation memories and terminology repositories linked to the project.
- ApiProjectFile – an item in the list of files that belongs to a project. Among properties of the object are file ID, name, size and a status of the file. The Status property informs you whether the file is waiting for processing (“Waiting”), had been processed successfully but no translated version of it was generated yet (“NotTranslated”), has been processed successfully and there’s a translated version of the file waiting for download (“Translated”). The state also indicates errors, such as source file processing failure (“ProcessingError”) or an error while generating a translated version of the file (“TranslationError”).
- ApiProjectFileContent – an object that represents a downloaded file. It includes file’s name and the content.
- ApiSystemLanguage – an object representing one of the languages supported by the system.
- ApiTeamMember – an item in a list of project team members. Represents a system user that was assigned a role (e.g. translator or proofreader) in the project.
- ApiTerminologyRepository – an item in the list of the terminology repositories linked to the project.
2. Get supported languages
That’s a block of code responsible for retrieving a list of all languages supported by the system. You will need at least two language objects later on to define project’s source and target languages. The project creation method requires you to provide respective language IDs. You may get to know that IDs by getting the list of all languages. Then you may select the appropriate ones.
To get the list call https://www.textunited.com/api/languages. The result is a collection of JSON objects that can be then converted into ApiSystemLanguage objects.
3. Get company users
This section gets and displays a list of all company users registered in Text United. You will need at least one of those users to specify a translator for the project.
4. 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 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:
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.
Now, let’s create the project object:
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:
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.
5. Get a collection of projects to see if it's ready for translation
It may take a while for the 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. A state of “In progress” indicates that the project was kicked off and delivered to translator(s). 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”.
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”.
6. Read project details
After the project is kicked off, you may verify its settings. Check it for its name, languages, project team, etc. Also you may check its progress, which obviously is 0% right after the project was started.
7. Read project files
Also, you can check the files in the project to see if they were processed with no errors. In response to the https://www.textunited.com/api/projectfiles?projectId=42217 request you’ll get basic information about all the files uploaded to the project (in this particular example we have only one file). The status “NotTranslated” indicates that the file was correctly process by the system (it was recognized and converted into segments). However there’s no translated version of the file generated yet. See ApiProjectFile object in chapter 0 for more information about possible values for the Status property.
Form the listing above we know the file name is SampleResouceFile.resx, it’s 6157 bytes in size and contains 18 translatable words.
8. Start translating
Project is ready, so now it’s time to translate it.
Let’s suppose only one segment in the package has been translated, as depicted below:
9. Read project details to see its progress
Reading project details periodically after it has been kicked off allows you to see the progress of translation. In this case the progress should be 33% approximately.
An output from the code:
is shown below:
Project ID: 42217
Status: In progress
10. Request generating translated versions of the files in the project
At any time when working with the project you may request generating a translated version of the file(s). Such request will create a target file with all the translations in place. Segments (resource strings) not translated at the moment will be kept in their original form.
11. Wait for the target file to be generated
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:
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.
12. Download the translated version of the file
Download a file by requesting https://www.textunited.com/api/projectfiles with three parameters:
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:
That can be then converted into a ApiProjectFileContent object and saved locally on disk. Remember that the content must be first decoded from Base64 string:
13. Updating file(s) in on-going project
When the project is 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
Files – collection of the file objects.
Each file must have the following properties:Filename – file name string
Content – Base64-encoded content of the file
See an JSON example for this call:
The request is served asynchronously. That means, you’ll immediately get a boolean response indicating whether it was accepted (true – when accepted). But the process may take a while. You’ll see the change in the project after 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.