Обмен XLIFF с CAT-системами

Статья обновлена 1 сентября 2026 г.

Когда перевод выполняют люди - штатные переводчики или бюро переводов, - они обычно работают в системе автоматизированного перевода (Computer Assisted Translation, или CAT): Trados, Phrase, Smartcat, Crowdin и подобных. Стандартный формат обмена с такими системами - XLIFF.

Подкоманды extract и compose команды yfm translate реализуют полный цикл такого перевода:

extract выгружает переводимый текст проекта в *.xliff файлы.
Файлы переводятся в CAT-системе.
compose собирает переведенные *.xliff обратно в файлы документации.

Как это работает

extract разбивает каждый файл документации на две части:

<файл>.xliff - переводимые сегменты: предложения, заголовки, ячейки таблиц;
<файл>.skl - скелет: исходный файл, в котором на месте сегментов стоят маркеры.

Разметка, код и Liquid-конструкции остаются в скелете и в CAT-систему не попадают - подробнее в разделе Как устроен перевод.

Оба файла сохраняются по пути целевого языка. Например, при переводе с ru на en из файла ru/guide/index.md получатся en/guide/index.md.xliff и en/guide/index.md.skl.

compose выполняет обратную операцию: находит в директории пары .xliff + .skl и собирает из каждой переведенный файл - en/guide/index.md. Файлы без пары пропускаются с предупреждением.

Пример полного цикла

# Выгрузить сегменты: в ./xliff появятся en/**/*.xliff и en/**/*.skl
yfm translate extract -i ./docs -o ./xliff --source ru --target en

# ...перевести *.xliff в CAT-системе...

# Собрать переведенные файлы в ./docs/en
yfm translate compose -i ./xliff -o ./docs

В CAT-систему передаются только *.xliff файлы, но при сборке переведенные *.xliff должны лежать рядом со своими *.skl - не удаляйте скелеты между шагами.

После compose переведенная версия собирается обычным yfm build.

Формат XLIFF

extract создает XLIFF версии 1.2. Каждый сегмент - элемент <trans-unit> с исходным текстом в <source>. Перевод должен попасть в элемент <target> - CAT-системы добавляют его сами:

<?xml version="1.0" encoding="UTF-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
  <file original="file.ext" source-language="ru-RU" target-language="en-US" datatype="markdown">
    <header>
      <skeleton>
        <external-file href="file.skl"></external-file>
      </skeleton>
    </header>
    <body>
      <trans-unit id="1">
        <source xml:space="preserve" xml:lang="ru-RU">Заголовок документа</source>
      </trans-unit>
    </body>
  </file>
</xliff>

Инлайн-разметка внутри сегмента - выделение, ссылки, код - кодируется служебными тегами <g> и <x/>. При переводе их нужно сохранять: по ним compose восстанавливает исходную разметку.

Параметры extract

Параметр	Описание
`--source`, `-sl`	Язык оригинала в формате ISO 639-1: `ru` или `ru-RU`. Обязательный
`--target`, `-tl`	Язык перевода: `en` или `en-US`. Можно указать несколько раз - выгрузка выполнится для каждого языка
`--filter`	Выгружать только файлы, достижимые из `toc.yaml`. По умолчанию выгружаются все файлы проекта
`--schema`	Пути к файлам с собственными схемами перевода для YAML и JSON. Можно указать несколько
`--no-ref-resolve`	Не разворачивать `$ref` в OpenAPI-спецификациях при выгрузке

Также поддерживаются общие параметры --input, --output, --files, --include и --exclude - см. Локализация.

Параметры compose

Параметр	Описание
`--input`, `-i`	Директория с парами `.xliff` + `.skl`. По умолчанию - директория запуска команды
`--output`, `-o`	Путь до корня проекта, в который нужно сохранить собранные файлы. По умолчанию совпадает с `input`
`--use-source`	Собрать файлы из исходного текста (`<source>`) вместо перевода. Полезно для отладки выгрузки

Параметры --include и --exclude фильтруют пары файлов так же, как при переводе - см. Локализация.