Smartcat integration 101: Basic scenario for content exchange

First of all, make sure you have read the Getting started guide (it’s short!).

Some terms to start with

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 machine 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.

Create a project and import a document

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.

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.

Update a document

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.

Calculate statistics

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.

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.

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.

Track translation status

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.

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

You can set up callbacks to track translation statuses.

Export the translation

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 <callbackURL>/document/exportRequestCompleted once the exported document is ready.

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}.