Smartcat integration 101: Basic scenario for content exchange

First of all, make sure you have read the Getting started guide (it’s short!) and chek out our educational video.

This scenario addresses two main entities: a project and a document.

A project is where you store your files, define source and target languages (yes, we support multilingual projects), set deadlines, attach linguistic assets, and connect AI translation.

A document is a file imported to Smartcat which can have import settings and one or more target languages. By default, an imported document has all target languages of the project. The document cannot have a deadline (but document assignments can). You can upload new documents to Smartcat or update existing ones.

Each project and each document have unique identifiers.

Let's start with the POST project/create method. Create a project with the most basic data: name and source/target languages. You can experiment with other parameters later. Please keep in mind that a parameter “assignToVendor” is required to request the method successfully. If you are testing the API in Swagger, do not include Content-Disposition, Content-Type, and Boundary to the body of your request.

See our project/create example

You can upload a document while creating a project using the documentProperties model. Alternatively, you can create an empty project and skip the documentProperties model. To import a file into an existing project, use the POST project/document method. Most parameters are optional for the basic scenario, so don’t dig deep in the beginning.

See our project/document example

If you have a newer document version (which is quite usual for a continuous scenario), you can update it in your project using the PUT document/update method and the document ID. The corresponding document will be overwritten in Smartcat. All translations that have already been done will be inserted in the new document through pretranslation.

See our document/update example

In some cases, you will need to calculate how many words your document has and how many of them are translation memory matches. To do this, call GET project/{projectid}/statistics.

See our project/{projectId}/statistics example

Note that the statistics will be calculated for all documents in the project. If you need statistics for a specific document, use GET document/statistics.

See our document/statistics example

If you only need the overall word count, without translation memory matches, you can simply use the wordsCount parameter returned by the GET document method.

See our document example

You can get information about your document at any time: progress for each workflow stage, task status, assignments, etc. To get this information for a specific document, use GET document with the corresponding document ID. The example would be the same as the one above.

To get information about the progress and statuses of all your documents at once and the overall project status and progress, use GET project/{projectid} with the corresponding project ID.

See our project/{projectId} example

You can set up callbacks to track translation statuses.

To export a translated document, use a POST document/export request. This requests Smartcat to render the final document. For smaller documents, you’ll receive the task ID in the response. For larger ones, rendering the target file will take some time depending on the document size and server load. In this case, Smartcat will send you a callback with the task ID to /document/exportRequestCompleted once the exported document is ready.

See our document/export example

PS: The parameter “stageNumber” defines a number of a stage in your project workflow. For example, 1 is for “Translation” if it’s the first stage, 2 is for “Editing”, and so on.

By the way, you can also export unfinished translations if you’re feeling impatient.

Once you have the task ID, you can download the resulting file with GET document/export/{taskid}.

See our document/export/{taskid} example