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>

Prevent <file original=“…”> from being parsed #️⃣

By default, Localazy stores several attributes from the file tag such as the languages, datatype and original filename making the reference to the file tag unique.

If your framework or library generates XLIFF files with the different original attribute per language, it’s not possible to correctly link translations together and thus it’s necessary to ignore it during the upload.

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

In such case, if the original attribute is required, you need to introduce a custom logic to restore the parameter as needed by your framework.

Prevent <file id=“…”> from being parsed #️⃣

Similarly to the previous chapter, if the id attribute is different per language, you can stop processing it.

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

Support for Unity #️⃣

XLIFF files generated by Unity have different original and id attributes for the file tag per language.

Add ignore_original and ignore_id to features in the upload section to upload existing translations from Unity and link them correctly.

Everything else works out of the box.

Handling locales #️⃣

By default, both source and target strings are processed and the locale is taken from the XLIFF file with fuzzy match being applied for the source language.

By adding dont_fuzzy_match_lang to features in the upload section, no fuzzy match is applied to the source langauge. And you can also change how languages are obtained from the XLIFF file 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.

Unicode entities #️⃣

By default, Unicode entities are encoded using the #&nnnn; format. To export Unicode entities as characters (e.g., smilies), which is necessary for XCode, add use_unicode 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.

Attributes of the translation unit #️⃣

By default, Localazy doesn’t store attributes of the <trans-unit>, except for important ones such as id. If you want to store all the attributes, add store_attrs feature.

This feature is only necessary for some frameworks that populate <trans-unit> with additional parameters.

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