Basic project creation flow

Please read carefully about authentication and prerequisites , and take into consideration that some steps might be done by Trados engineering.

Details about what are the rate limits for Trados Cloud Platform API can be found on API rate limits page.

Additional information regarding file and project size limits can be found here.

Note

This small Postman collection can help you get started with the basic project creation flow. For details on Postman setup please see the main Postman page.

In the Create Project endpoint body, the projectTemplate value should be replaced with a valid templateId. From that point on all the necessary identifiers will be automatically populated throughout Postman.

Check the Multi-Region page for regional API details.

Steps to create a basic translation project:

  1. Create Project
  2. Add project source file
  3. Start Project
  4. List Project's Tasks
  5. List Project Target Files
  6. Download File
  7. Complete Project
  8. List Projects

1. Create Project

Creates a new project.

Endpoint: POST /projects

For running this endpoint you need to supply the required project details (body tab in Postman):

Note

POST https://api.{REGION_CODE}.cloud.trados.com/public-api/v1/projects

{
	"name": "Name of the Project",
	"description": "Test Project",
	"dueBy": "2021-09-04T08:14:05.858Z",
	"projectTemplate": {
		"id": "xxxxxxxxxxxxxxxxxxxxxxxx" // Provided by RWS
	},
	"languageDirections": [
		{
			"sourceLanguage": {
				"languageCode": "en-US"
			},
			"targetLanguage": {
				"languageCode": "fr-FR"
			}
		}
	]
}

Source and Target Language Codes can be obtained from here.

The API should respond with:

  • HTTP Status Code: 201 Created.
  • Body - your project details consisting of projectId, project name, language direction, location and other optional fields.

Example:

{
    "id": "xxxxxxxxxxxxxxxxxxxxxxxx", // The project identifier.
    "name": "Name of the Project",
    "languageDirections": [
        {
            "sourceLanguage": {
                "languageCode": "en-US",
                "englishName": "English (United States)"
            },
            "targetLanguage": {
                "languageCode": "fr-FR",
                "englishName": "French (France)"
            }
        }
    ],
    "location": {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "Project Location"
    }
}

Create simple project


Scenario:

If your company has multiple divisions, you can imagine a hierarchy like this:

YOUR COMPANY

  • Marketing Division
  • Management Division
  • HR Division

If you want to create projects for different divisions, this can be done by using the location parameter, which will be added in the body. When location is not set, the system will try to create the resource in the higher folder in the hierarchy, the Root folder. It might not have access to that folder and the request will fail with forbidden error.

{
	"name": "Name of the Project",
	"description": "Test Project",
	"dueBy": "2021-09-04T08:14:05.858Z",
	"projectTemplate": {
		"id": "xxxxxxxxxxxxxxxxxxxxxxxx" // Provided by RWS
	},
	"languageDirections": [
		{
			"sourceLanguage": {
				"languageCode": "en-US"
			},
			"targetLanguage": {
				"languageCode": "fr-FR"
			}
		}
	],
	"location": "xxxxxxxxxxxxxxxxxxxxxxxx" // Provided by RWS
}

Using this request your project will be created in the specified Division and it will be visible only there.

Detailed information about location and folders can be found on the How to use location and folders page.

Create project with location

More details about this endpoint can be found here.

2. Add Source File

Adds a source file to the project.

Endpoint: POST /projects/{projectId}/source-files

For running this endpoint you need to:

  • Replace {projectId} from the URL with the identifier received from the Create Project endpoint response:
Note

POST https://api.{REGION_CODE}.cloud.trados.com/public-api/v1/projects/{projectId}/source-files

  • Add the file to the request body.
  • Complete the details from Body tab - Properties field.
Properties field:
{
	"language": "en-US",
	"type": "native",
	"role": "translatable",
	"name": "nameOfTheFile.extension"
}

Responses:

  • HTTP Code 201 Created.
  • Body - a list with the identifier, name and role of the file.

Add source file

More details about this endpoint can be found here.

3. Start Project

Starts a project.

Endpoint: PUT /projects/{projectId}/start

For running this endpoint you need to:

  • Replace {projectId} from the URL with the identifier received from the Create Project endpoint response:
Note

PUT https://api.{REGION_CODE}.cloud.trados.com/public-api/v1/projects/{projectId}/start

Responses:

  • HTTP Code 202 Accepted

Start project

More details about this endpoint can be found here.

4. List Project's Tasks

List the tasks of a specific project. If all the tasks have the status completed, all the files are translated.

Endpoint: GET /projects/{projectId}/tasks

For running this endpoint you need to:

  • Replace {projectId} from the URL with the identifier received from the Create Project endpoint response:
Note

GET https://api.{REGION_CODE}.cloud.trados.com/public-api/v1/projects/{projectId}/tasks?fields=taskType,status

Use ?fields=taskType if you want to observe the task name.

Responses:

  • HTTP Code 200 Ok.
  • Body - a list with task identifier and status.

Example:

{
	"items": [
		{
			"id": "613f621fe5ed2804ba31870e",
			"status": "completed",
			"taskType": {
				"id": "607932f25c7cc701241f0f60",
				"key": "scan",
				"name": "File Type Detection"
			}
		},
		{
			"id": "613f623040d9943308ef7c3b",
			"status": "completed",
			"taskType": {
				"id": "607932f3ce8af15851b70205",
				"key": "convert",
				"name": "File Format Conversion"
			}
		},
                ...
	],
	"itemCount": 11
}

List project's task

More details about this endpoint can be found here.

5. List Project Target Files

Retrieves the target fileId for a project and the latest version for the translated file.

Endpoint: GET /projects/{projectId}/target-files

For running this endpoint you need to:

  • Replace {projectId} from the URL with the identifier received from the Create Project endpoint response:
Note

GET https://api.{REGION_CODE}.cloud.trados.com/public-api/v1/projects/{projectId}/target-files?fields=latestVersion

Responses:

  • HTTP Code 200 Ok.
  • Body - a list with objects that contain:
    • source file and target file identifiers
    • source and target languages

Example:

{
	"items": [
		{
			"id": "613f623ae5ed2804ba318a40", // This is the target file identifier.
			"latestVersion": {
				"id": "613f628540d9943308ef8497", // This is the file version identifier.
				"type": "native"
			}
		},
		{
			"id": "613f623ae5ed2804ba318a43",
			"latestVersion": {
				"id": "613f628a40d9943308ef84cd",
				"type": "native"
			}
		}
	],
	"itemCount": 2
}

List project target files

More details about this endpoint can be found here.

6. Download File

Downloads the translated file.

Endpoint: GET /projects/{projectId}/target-files/{targetFileId}/versions/{fileVersionId}/download

For running this endpoint you need to:

  • Replace {projectId} from the URL with the identifier received from the Create Project endpoint response
  • Replace {targetFileId} from the URL with the identifier received from the List Project Target Files endpoint response
  • Replace {fileVersionId} from the URL with the identifier received from the List Project Target Files endpoint response
Note

GET https://api.{REGION_CODE}.cloud.trados.com/public-api/v1/projects/{projectId}/target-files/{targetFileId}/versions/{fileVersionId}/download

Responses:

  • HTTP Code 200 OK.
  • Body - the translated file. The file can be also saved from Save Response option.

Download file

More details about this endpoint can be found here.

7. Complete Project

Marks a project as completed.

Endpoint: PUT /projects/{projectId}/complete

For running this endpoint you need to:

  • Replace {projectId} from the URL with the identifier received from the Create Project endpoint response
Note

PUT https://api.{REGION_CODE}.cloud.trados.com/public-api/v1/projects/{projectId}/complete

Responses:

  • HTTP Code 204 No Content.

Complete project

More details about this endpoint can be found here.

8. List Projects

Retrieves a list of all the projects in the account.

Endpoint: GET /projects

For running this endpoint make a request to:

Note

GET https://api.{REGION_CODE}.cloud.trados.com/public-api/v1/projects

Responses:

  • HTTP Code 200 OK.
  • Body - a list of projects with details consisting of project identifier, project name, language direction, location and other optional fields

Example:

{
	"items": [
		{
			"id": "xxxxxxxxxxxxxxxxxxxxxxxx",
			"name": "Translation Project 1",
			"languageDirections": [
				{
					"sourceLanguage": {
						"languageCode": "en-US",
						"englishName": "English (United States)"
					},
					"targetLanguage": {
						"languageCode": "fr-FR",
						"englishName": "French (France)"
					}
				}
			],
			"location": {
				"id": "xxxxxxxxxxxxxxxxxxxxxxxx",
				"name": "Project Location"
			}
		},
		{
			"id": "xxxxxxxxxxxxxxxxxxxxxxxx",
			"name": "Translation Project 2",
			"languageDirections": [
				{
					"sourceLanguage": {
						"languageCode": "en-US",
						"englishName": "English (United States)"
					},
					"targetLanguage": {
						"languageCode": "fr-FR",
						"englishName": "French (France)"
					}
				}
			],
			"location": {
				"id": "xxxxxxxxxxxxxxxxxxxxxxxx",
				"name": "Project Location"
			}
		}
	],
	"itemCount": 2
}

List projects

More details about this endpoint can be found here.