File Format - XLIFF 1.2

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

Selected elements of XLIFF 1.2 are supported, and the format is fully compliant with Apple’s XLIFF files generated by XCode including Apple’s plural extension (described below).

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2"       
       version="1.2">

  <file original="Interface.storyboard" source-language="en" target-language="en" datatype="plaintext">
    <body>
      <trans-unit id="text1" xml:space="preserve">
        <source>Source Text 1</source>
        <target>Translated Text 1</target>
        <note>Comment for the translator.</note>
      </trans-unit>
      <trans-unit id="text2" xml:space="preserve">
        <source>Source Text 2</source>
        <target>Translated Text 2</target>
      </trans-unit>
    </body>
  </file>

</xliff>

Supported elements

<file>

Attributes original, source-language, target-language, and datatype are used for obtaining locale information and retained.

<body>

No extra functionality is provided.

<trans-unit>

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

<trans-unit id="skipped_text1" xml:space="preserve" translate="yes">
  <source>Skipped Source Text 1</source>
  <target>Skipped Translated Text 1</target>
</trans-unit>

Sub-elements source, target and note are supported.

<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">
  <trans-unit id="inner_text1" xml:space="preserve">
    <source>Inner Source Text 1</source>
    <target>Inner Translated Text 1</target>
  </trans-unit>
</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 <trans-unit id=".."> tag is included in the string key. You can enable the omit_id_for_source_is_key feature to remove it. With this feature enabled, numeric id is generated for each of the <trans-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.

<trans-unit id="array[1]" xml:space="preserve">
  <source>Array Item 1</source>
</trans-unit>

<trans-unit id="array[13]" xml:space="preserve">
  <source>Array Item 13</source>
</trans-unit>

<trans-unit id="array[27]" xml:space="preserve">
  <source>Array Item 27</source>
</trans-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.

<trans-unit id="plural[one]" xml:space="preserve">
  <source>You have 1 item.</source>
</trans-unit>

<trans-unit id="plural[other]" xml:space="preserve">
  <source>You have {count} items.</source>
</trans-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.

<trans-unit id="/plural string:dict/count:dict/one:dict/:string" xml:space="preserve">
  <source>You have 1 item.</source>
  <target>Máte 1 položku.</target>
</trans-unit>

<trans-unit id="/plural string:dict/count:dict/other:dict/:string" xml:space="preserve">
  <source>You have {count} item.</source>
  <target>Máte {count} položek.</target>
</trans-unit>

ICU plurals

Enabled by parse_plurals_icu in features in the upload section.

<trans-unit id="icu_plural" xml:space="preserve">
  <source>You {count, plural, =0 {have no projects} one {have # project} other {have # projects}}.</source>
</trans-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.