Exporting XLIFF files from Smartcat and uploading changes via the API

A description of necessary requests and responses

You can use our API to export a bilingual XLIFF file from Smartcat for any document at any stage of completion. The exported file conforms to the XLIFF 1.2 standard and contains information about the segment status, the stage in the workflow, and locks. After you add or change a translation on your side, you can return either the entire file or individual segments. For re-importing, you can configure whether to confirm segments and whether to write over the translation text if it has changed since the last export of the XLIFF.

Let's look at each step in the workflow.

How to find the document you want to export

First, you need to request a list of all projects that are available in your account. To do this, use GET project/list

The response contains information about available projects and the documents they contain (their names, IDs, and language pairs).

If you want to request a list of documents for a specific project using the project ID, use GET project/{projectId}

The response contains information about documents in the project, including their names, IDs, and language pairs.

How to export files from Smartcat

If you know the document ID, you can request exporting a bilingual version of the document (XLIFF) using POST document/export

You can set one or more document IDs in the DocumentIds parameter. The parameter value must contain the ID of the document being updated and the ID of the translation language, in the format DocumentID_LanguageID.

To export XLIFF format, the type parameter must be set to xliff. If this parameter is omitted (or the value is set to 1), it means to export the translated document, rather than the bilingual format.

How to import files back into Smartcat

To re-import the modified XLIFF file back to Smartcat, use PUT document/translateWithXliff

For the documentId parameter, specify the ID of the document being updated and the ID of the translation language in the format DocumentID_LanguageID. In the request body, pass the file in XLIFF format that you previously exported from Smartcat.

How to import one or more segments

You can re-import an XLIFF file that contains only certain segments. Since the segments have unique identifiers, the translation texts from the XLIFF are copied to the correct segments in Smartcat, even if they are in a different order.

How to configure importing changed segments

You can customize Smartcat's behavior when importing changed segments. Specifically, you can configure whether to confirm changed segments automatically, and whether to replace the translation text if it was changed by another user in Smartcat while the XLIFF was being edited. Set these options in the parameters for PUT document/translateWithXliff.

Segment confirmation is controlled by the value of the confirmTranslation parameter. If true, all imported segments are confirmed automatically. If you don't want to do that, set it to false.

Replacing the translation text in segments is controlled by the value of the overwriteUpdatedSegments parameter. If true, the text from the imported segments replaces the translated segments in Smartcat, even if they have been changed by another user. If you don't want to do that, set it to false.

How to check that everything was imported successfully

To get the status of the file import, use GET document/translate/status. In the value of the documentId parameter, specify the ID of the updated document and the language ID in the format DocumentID_LanguageID. One of the following values is returned in the response: InProgress (task in progress), Faulted (task failed with an error) or Completed (task completed successfully).

You can also configure receiving notifications. To do this, use POST callback.

When all the translations have been imported from the XLIFF file, a POST notification is sent to the specified URL: /document/translationImportCompleted. The body of the notification contains an array of IDs of updated documents. See also our Overview of callback notifications.