Smartcat integration 101: Basic scenario for content exchange

Learn how to manage projects and documents on Smartcat using developer documentation, including creating projects, importing and updating documents, calculating document statistics, tracking translation status, and exporting translated documents using specific methods and models.

Developer documentation has been migrated to the dedicated resource developers.smartcat.com. This page is deprecated but will temporarily remain available for your convenience.

💡

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

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

Request URL: 
https://smartcat.ai/api/integration/v1/project/create

Headers:
Content-Type: multipart/form-data; boundary=--------------------SmartCATe8bf0f27d7
Authorization: Basic dGVzdGFwaUJhY2t1cDoxMjM0NTY=

Body:
----------------------SmartCATe8bf0f27d7
Content-Disposition: form-data; name="Test"; filename="test.txt"
Content-Type: application/octetstream
One. Two. Three.
----------------------SmartCATe8bf0f27d7
Content-Disposition: form-data; name="model"
Content-Type: application/json
{
"name":" API Project",
"sourceLanguage": "en",
"targetLanguages": ["ru"],
"assignToVendor": false
}
----------------------SmartCATe8bf0f27d7--

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

Request URL:
https://smartcat.ai/api/integration/v1/project/document?projectId={projectId}

Headers:
Content-Type: multipart/form-data; boundary=--------------------SmartCATe8bf0f27d7
Authorization: Basic dGVzdGFwaToxMjM0NTY=

Body:
----------------------SmartCATe8bf0f27d7
Content-Disposition: form-data; name="txt"; filename="txt.txt"
Content-Type: application/octetstream
Text
----------------------SmartCATe8bf0f27d7--

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.

See our document/update example

Request URL:
https://smartcat.ai/api/integration/v1/document/update?documentId={documentId_languageId}

Headers:
Content-Type: multipart/form-data; boundary=--------------------SmartCATe8bf0f27d7
Authorization: Basic dGVzdGFwaToxMjM0NTY=

Body:
----------------------SmartCATe8bf0f27d7
Content-Disposition: form-data; name="txt"; filename="txt.txt" Content-Type: application/octetstream
Text update
----------------------SmartCATe8bf0f27d7--

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.

See our project/{projectId}/statistics example

Request URL: 
https://smartcat.ai/api/integration/v1/project/{projectId}/statistics?onlyExactMatches=false

Headers:
Authorization: Basic dGVzdGFwaToxMjM0NTY=

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

Request URL: 
https://smartcat.ai/api/integration/v1/document?documentId={documentId_languageId}

Headers:
Authorization: Basic dGVzdGFwaToxMjM0NTY=

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

Request URL: 
https://smartcat.ai/api/integration/v1/project/{projectId}

Headers:
Authorization: Basic dGVzdGFwaToxMjM0NTY=

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 /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

Request URL: 
https://smartcat.ai/api/integration/v1/document/export/{taskid}

Headers:
Authorization: Basic dGVzdGFwaToxMjM0NTY=