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...]

DESCRIPTION
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:

1.  Extract translatable content from a ort(5) configuration into an XLIFF file.

2.  Give the XLIFF file a target language and translate the strings.

3.  Merge the XLIFF file back into the original ort(5) with -j. Already-translated labels for the given language are not overriden by default.

4.  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 "&amp;", "&lt;", "&gt;", "&apos;", and "&quot;", respectively, when compared with source identifiers in XLIFF files. Thus, "<source>a&lt;b&amp;c</source>" matches with the label "a<b&c".

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

EXIT STATUS

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

SEE ALSO
ort-javascript(1), ort(5)

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.