ORT-XLIFF(1)

NAME

ort-xliff — extract and merge translatable strings from ort configurations

SYNOPSIS

ort-xliff [-c] -j config [xliff]

ort-xliff [-c] -j [config...] -x [xliff...]

ort-xliff [-c] -u config [xliff]

ort-xliff [-c] -u [config...] -x [xliff]

ort-xliff [-c] [config...]

The ort-xliff utility accepts ort(5) config files, defaulting to standard input, and extracts, merges, and updates translatable strings. The translated strings are used only by ort-javascript(1). The arguments are as follows:

-c: Instead of creating an empty target when extracting strings, joining translation, or updating with new translations, fill in the target with the source.
-j: Merges one or more xliff files with an untranslated config, producing another configuration containing the translated strings.
-u: Update the xliff file with new translation labels found in config.
xliff: An XLIFF 1.2 file containing translated strings.
config: A ort(5) configuration file. There may be multiple files in a single configuration.

By default, ort-xliff produces results to standard output.

When invoked with -j or -u, multiple ort(5) configuration files and XLIFF files as arguments must be broken up by the -x flag, which signals the beginning of the XLIFF files.

Translatable content in ort(5) is limited to jslabel phrases for enumerations and bitfields.

The usual usage sequence is as follows:

Extract translatable content from a ort(5) configuration into an XLIFF file.
Give the XLIFF file a target language and translate the strings.
Merge the XLIFF file back into the original ort(5) with -j. Already-translated labels for the given language are not overriden by default.
Use the produced configuration for further use in ort-javascript(1).

With these steps, integral enumeration values produced by the JSON output of ort-c-source(1) and ort-c-header(1) may be translated into human-readable, language-specific labels.

Encoding

Labels with XML special characters "&", "<", ">", "'", and """ encode as the XML escaped "&", "<", ">", "'", and """, respectively, when compared with source identifiers in XLIFF files. Thus, "<source>a<b&c</source>" matches with the label "a<b&c".

All other XML escapes are passed through verbatim, so "<source>©</source>" matches with the label "©" instead of the copyright marker. Numbered entities should be encoded in their UTF-8 representations instead.

EXIT STATUS

The ort-xliff utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

Take a dummy configuration foo.ort containing the following:

enum foo {
  item bar 0 jslabel "bar";
  item foo 1 jslabel "foo";
};

Begin by extracting translatable strings from the input.

% ort-xliff foo.ort
<xliff version="1.2">
  <file target-language="TODO" tool="ort-xliff">
    <body>
      <trans-unit id="1">
        <source>bar</source>
      </trans-unit>
      <trans-unit id="2">
        <source>foo</source>
      </trans-unit>
    </body>
  </file>
</xliff>

Change the language into something useful, such as "fr", and translate the strings into "le bar" and "le foo", respectively. Then join the output, foo.fr.xliff, with the input configuration.

% ort-xliff -j foo.ort foo.fr.xliff
enum foo {
  item bar 0
    jslabel "bar"
    jslabel.fr "le bar";
  item foo 1
    jslabel "foo"
    jslabel.fr "le foo";
};

This output file can then be used with ort-javascript(1) to have per-language label filling.

Multiple configuration files, when joining, may also be specified.

% ort-xliff -j foo1.ort foo2.ort -x foo.fr.xliff

The configuration or XLIFF files may also be passed on standard input by omitting the file. In the first case, the configuration is omitted. (The special “--” is used to prevent -x from being interpreted as a command-line option.) In the second case, it's the translation file.

% ort-xliff -j -- -x foo.fr.xliff < foo.ort
% ort-xliff -j foo1.ort foo2.ort -x < foo.xliff

CAVEATS

ort-xliff currently only supports language tags without non-alpha characters, e.g., the hyphen. These are stipulated by RFC 4646, and will be added at a later date.