Documentation section

File Format - XLIFF 2.0

Learn how to use Localazy CLI for app and software localization with XLIFF 2.0.

Selected elements of XLIFF 2.0 are supported, and we added extra support for Apple’s plural extension, arrays, and other forms of plurals.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="en" trgLang="cs">

  <file id="f1" original="soubor.cs" datatype="plaintext">

    <unit id="string_key">

      <notes>
        <note id="comment_1">Comment for translator.</note>
      </notes>
  
      <segment id="seg_1">
        <source>PART 1 EN</source>
        <target>PART 1 CS</target>
      </segment>

      <segment id="seg_2">
        <source>PART 2 EN</source>
        <target>PART 2 CS</target>
      </segment>

    </unit>

  </file>
</xliff>

Supported elements 🔗

<xliff> 🔗

Attributes srcLang and trgLang are used for obtaining locale information.

<file> 🔗

Attributes id, original, and datatype are stored and retained in translated files.

<unit> 🔗

If the attribute translate is set to no or false, the phrase is skipped.

<unit id="skipped_text1" translate="yes">
  ...
</unit>

<notes> and <note> 🔗

Allows defining comments and context information for translators.

<unit id="string_key">

  <notes>
    <note id="comment_1">Comment for translator.</note>
  </notes>
 
  ...

</unit>

<segment> 🔗

Multiple segments inside one <unit> are supported, but the segments are imported as a separate string.

<unit id="string_key">

  <segment id="segment_1">
    <source>Original String: Segment 1</source>
    <target>Translated String: Segment 1</target>
  </segment>

  <segment id="segment_2">
    <source>Original String: Segment 2</source>
    <target>Translated String: Segment 2</target>
  </segment>

</unit>

<group> 🔗

If the group element contains id, it’s retained, and stored data is structured accordingly. Without id, the group is just removed.

If the attribute translate is set to no or false, the whole group is skipped.

<group id="" translate="yes">
  ...
</group>

Handling locales 🔗

By default, both source and target strings are processed and the locale is taken from the XLIFF file. You can change this behavior by adding features mentioned in the table below to features in the upload section.

Feature Description
dont_parse_source Do not parse source strings.
dont_parse_target Do not parse target strings.
use_project_lang Use the project base language for source strings.
use_defined_lang_for_source Use language defined for the uploaded file for source strings.
use_defined_lang_for_target Use language defined for the uploaded file for target strings.

Features use_project_lang, use_defined_lang_for_source and use_defined_lang_for_target cannot be combined and they are processed in the same order as mentioned.

XML entities 🔗

By default, XML entities are converted while importing your file. They may not be converted back while exporting it, because it’s not necessary.

It’s possible to output certain XML 1.1 entities (such as &apos;) in the final file. This feature can be enabled by adding output_entities to features in the upload section.

This feature is useful for Angular to get the output in the same format as input.

HTML entities 🔗

HTML entities are not allowed in XLIFF files because they are not defined in the XML standard. Localazy can convert HTML entities to their Unicode representation when the file is imported.

This feature can be enabled by adding decode_html_entities to features in the upload section.

Key in source 🔗

Some frameworks such as Symfony, use the <source> tag for string keys. You can enable support for this by adding source_is_key to features in the upload section.

This feature can be used together with use_project_lang or use_defined_lang_for_source.

By default, id from the <unit id=".."> tag is included in the string key. You can enable the omit_id_for_source_is_key feature to remove it. Please note that it can have some consequences related to multiple segments as it’s no longer possible to group them by key. With this feature enabled, numeric id is generated for each of the <unit> tags.

Array support 🔗

Arrays are good but beware of changing the number of items to prevent mismatching translations. If your files contain incomplete arrays, don’t use array features at all.

This feature can be enabled by adding parse_array to features in the upload section.

<unit id="array[1]">
  <segment id="s1">
    <source>Array Item 1</source>
  </segment>
</unit>

<unit id="array[13]">
  <segment id="s1">
    <source>Array Item 13</source>
  </segment>
</unit>

<unit id="array[27]">
  <segment id="s1">
    <source>Array Item 27</source>
  </segment>
</unit>

The code above will be processed as an array and additional metadata will be stored, so Localazy can restore the indexes correctly.

All valid indexes are processed where the valid index is a non-negative integer value.

Plurals support 🔗

This feature can be enabled by adding parse_plurals to features in the upload section.

<unit id="plural[one]">
  <segment id="s1">
    <source>You have 1 item.</source>
  </segment>
</unit>

<unit id="plural[other]">
  <segment id="s1">
    <source>You have {count} items.</source>
  </segment>
</unit>

Apple’s plural extension 🔗

The plural format below is fully supported. Enable the support with parse_plurals_ios in features in the upload section.

<unit id="/plural string:dict/count:dict/one:dict/:string">
  <segment id="s1">
    <source>You have 1 item.</source>
    <target>Máte 1 položku.</target>
  </segment>
</unit>

<unit id="/plural string:dict/count:dict/other:dict/:string">
  <segment id="s1">
    <source>You have {count} item.</source>
    <target>Máte {count} položek.</target>
  </segment>
</unit>

ICU plurals 🔗

Enabled by parse_plurals_icu in features in the upload section.

<unit id="icu_plural" xml:space="preserve">
  <segment id="s1">
    <source>You {count, plural, one {have # project} other {have # projects}}.</source>
  </segment>
</unit>

Only one ICU plural can be used in the string as otherwise, it wouldn’t be possible to convert it to a specific Localazy plural structure. If more than two ICU plurals are contained, the string is kept in the original form.

Allowed plurals types are: zero (=0), one (=1), two (=2), few, many, other.

Other ICU types like gender, number, etc. can be used but will not be converted and will be kept in string in the original form.

Filtering untranslated strings 🔗

By default, when the output file is generated, Localazy uses texts from the source languages when the translation in the exported language is missing.

This approach is safeguarding you from missing keys that can lead to crashes in some solutions/frameworks.

This feature can be disable by adding filter_untranslated to features in the upload section and reuploading your source language file.