Экспорт файлов XLIFF из Smartcat и возврат изменений через API

Описание необходимых запросов и ответов

Возможности нашего API позволяют экспортировать из Smartcat двуязычный XLIFF-файл для любого документа на любой стадии работы. Экспортируемый файл соответствует стандарту XLIFF 1.2 и содержит в себе информацию о статусе сегмента, о его этапе работы и блокировке. После добавления или изменения перевода на вашей стороне, вы можете вернуть как целый файл, так и его отдельные сегменты. При обратном импорте вы сможете настроить подтверждение сегментов и необходимость перезаписи текста перевода, если он изменился с момента последнего экспорта XLIFF.

Рассмотрим пошаговый сценарий работы

Как найти нужный документ для экспорта

Для начала нужно запросить список всех проектов, доступных в аккаунте. Это можно сделать с помощью метода GET: /api/integration/v1/project/list

В полученном ответе будет содержаться информация о доступных проектах и содержащихся в них документах (их имена и идентификаторы и языковые пары).

Если вы хотите запросить список документов у конкретного проекта, используя его идентификатор, вы можете воспользоваться методом GET: /api/integration/v1/project/{projectId}

В полученном ответе будет содержаться информация о документах в проекте, включая их имена, идентификаторы и языковые пары.

Как экспортировать файлы из Smartcat

Зная идентификатор документа, запросить экспорт двуязычного представления документа (XLIFF) можно с помощью метода

POST: api/integration/v1/document/export

В параметре documentIds вы можете указать один или несколько идентификаторов документов. Значение параметра должно содержать идентификатор обновляемого документа и идентификатор языка перевода в виде DocumentID_LanguageID.

Для экспорта XLIFF значение параметра type должно быть 5. Отсутствие параметра (а также значение 1) означает экспорт перевода документа, а не его двуязычного представления.

Как импортировать файлы обратно в Smartcat

Вернуть модифицированный XLIFF-файл обратно в Smartcat можно с помощью метода

PUT: api/integration/v1/document/translateWithXliff

В качестве параметра documentId укажите идентификатор обновляемого документа и идентификатор языка перевода в виде DocumentID_LanguageID. В теле запроса передайте файл в формате xliff, который был ранее экспортирован из Smartcat.

Как импортировать один или несколько сегментов

Вы можете вернуть в Smartcat файл XLIFF, который будет содержать только определённые сегменты. Благодаря наличию уникальных идентификаторов, тексты переводов из XLIFF попадут в нужные сегменты в SmartCAT, даже если они будут в другом порядке.

Как настроить импорт изменённых сегментов

Вы можете настроить поведение Smartcat при импорте изменённых сегментов — настроить подтверждение изменённых сегментов и необходимость замены текста, если за время работы с файлом XLIFF текст перевода в Smartcat был изменён другим пользователем. Настройки задаются с помощью параметров метода PUT: api/integration/v1/document/translateWithXliff.

Настройка подтверждения сегментов управляется значением параметра confirmTranslation. Если он имеет значение true, это значит, что все импортируемые сегменты будут подтверждены. Если вы не хотите этого делать, передайте значение false.

Настройки замены текста в сегментах управляется значением параметра overwriteUpdatedSegments. По умолчанию он имеет значение true, это значит, что текст в импортируемых сегментах заменит текст перевода в Smartcat даже если он был изменён другим пользователем. Если вы не хотите этого делать, передайте значение false.

Как узнать, всё ли импортировалось успешно

Чтобы получить информацию о статусе импорта файла, используйте метод

GET: /api/integration/v1/document/translate/status, где в значении параметра documentId укажите идентификатор обновляемого документа и идентификатор языка перевода в виде DocumentID_LanguageID. В качестве ответа вернётся одно из значений: InProgress (задача в процессе выполнения), Faulted (задача завершена с ошибкой) или Completed (задача успешно завершена).

Вы также можете создать настройку приёма уведомлений с помощью метода POST: api/integration/v1/callback.
По окончании импорта переводов из файла XLIFF на указанный URL придёт уведомление POST: <callbackUrl>/document/translationImportCompleted. Тело уведомления будет содержать массив идентификаторов обновлённых документов. Посмотрите также наш обзор callback-уведомлений.

Нашли, что искали?