XLIFF exchange with CAT tools
When translation is done by people - in-house translators or an agency - they usually work in a Computer Assisted Translation (CAT) tool: Trados, Phrase, Smartcat, Crowdin, and the like. The standard exchange format for such tools is XLIFF.
The extract and compose subcommands of the yfm translate command implement the full cycle of such translation:
extractexports the translatable project text into*.xlifffiles.- The files are translated in a CAT tool.
composeassembles the translated*.xliffback into documentation files.
How it works
extract splits each documentation file into two parts:
<file>.xliff- translatable segments: sentences, headings, table cells;<file>.skl- the skeleton: the source file with markers in place of the segments.
Markup and Liquid constructs are preserved in the skeleton or auxiliary XLIFF tags. Code block content is exported in full by default, and inline code is included in segment text between auxiliary tags. The tags preserve formatting, but do not exclude the text itself from translation.
To exclude a code block, add translate=no after the language. For an inline fragment, use :no-translate[], keeping backticks inside the brackets if needed:
Specify :no-translate[`NODE_1`].
```plaintext translate=no
export NODE_1="192.168.1.101"
```
Other ways to exclude content are described in Excluding content from translation. The --code option applies to provider translation and does not change the extraction mode of the extract subcommand.
Both files are saved under the target language path. For example, when translating from ru into en, the file ru/guide/index.md produces en/guide/index.md.xliff and en/guide/index.md.skl.
compose performs the reverse operation: it finds .xliff + .skl pairs in a directory and assembles a translated file from each - en/guide/index.md. Files without a pair are skipped with a warning.
Full cycle example
# Export segments: en/**/*.xliff and en/**/*.skl appear in ./xliff
yfm translate extract -i ./docs -o ./xliff --source ru --target en
# ...translate *.xliff in a CAT tool...
# Assemble translated files into ./docs/en
yfm translate compose -i ./xliff -o ./docs
Only the *.xliff files are handed over to the CAT tool, but during assembly the translated *.xliff must sit next to their *.skl - don't delete the skeletons between steps.
After compose, the translated version is built with a regular yfm build.
XLIFF format
extract produces XLIFF version 1.2. Each segment is a <trans-unit> element with the source text in <source>. The translation must go into the <target> element - CAT tools add it themselves:
<?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">Document title</source>
</trans-unit>
</body>
</file>
</xliff>
Inline markup inside a segment - emphasis, links, code - is encoded with the auxiliary <g> and <x/> tags. They must be preserved during translation: compose uses them to restore the original markup.
extract parameters
|
Parameter |
Description |
|---|---|
|
|
Source language in ISO 639-1 format: |
|
|
Target language: |
|
|
Export only files reachable from |
|
|
Paths to files with custom translation schemas for YAML and JSON. Several paths can be specified |
|
|
Do not resolve |
The common parameters --input, --output, --files, --include, and --exclude are also supported - see Localization.
compose parameters
|
Parameter |
Description |
|---|---|
|
|
Directory with |
|
|
Path to the project root where the assembled files should be saved. Defaults to |
|
|
Assemble files from the source text ( |
The --include and --exclude parameters filter file pairs the same way as during translation - see Localization.