XLIFF (XML Localization Interchange File Format) files are used to standardize the exchange of localization data across different tools and platforms. Lokalise supports XLIFF files (.xlf, .xliff) version 1.2 as per the XLIFF specification, allowing for efficient management and translation of your localization projects.

Technical information

Overview

Format name:
XLIFF

File extensions:
.xlf, .xliff

Common use cases:
Standardizing the exchange of localization data for various platforms, including Angular i18n, Apple iOS and macOS, and Symfony PHP.

Technical details:

Structure: XLIFF files are XML-based and consist of various elements and attributes that define the source and target languages, as well as the translation units and their associated metadata.
Encoding: UTF-8

Example:
Here's an example of a typical XLIFF file used for localization:

<xliff version="1.2">
  <file source-language="en" target-language="de" original="example">
    <body>
      <trans-unit id="1" datatype="plaintext">
        <source>Hello, world!</source>
        <target state="translated">Hallo, Welt!</target>
      </trans-unit>
    </body>
  </file>
</xliff>

Using with Lokalise

Lokalise supports XLIFF files, making it easy to manage and translate your localization strings efficiently.

Supported project types

Please note that XLIFF files can be uploaded only to Web and mobile projects.

Import

When importing an XLIFF file, Lokalise tries to find the source and target language tags and match them against existing languages. If only one of either source or target languages is defined in the file, the specified language will be imported.

However, XLIFF specifications indicate that both source and target languages must be specified. If you manually specify the language during import, it will assume the target language is the one you are setting.

Export

Select the appropriate platform's format when exporting. Choosing Angular XLIFF causes plurals (see below) to be exported in ICU format (you can also check our blog post which gives a nice introduction to the ICU message format). As for other XLIFF formats, plurals will be exported as JSON objects with keys and values.

Plural support

We support ICU message format and JSON encoded string plurals. Currently, this is the predefined set of plural forms according to the Unicode CLDR Project, described in the Plural Rules specification. Each language has its own set of tags specified in the Language Plural Rules.

For Apple XLIFF files, we also support the Apple format for keeping plurals. It's similar to the process in .stringsdict files as it contains format keys and plural forms. There are keys for each format plural form and one for format. See the example for details:


  <file original="Hello/en.lproj/Localizable.stringsdict" source-language="en" datatype="plaintext" target-language="ru">
    <body>
      <trans-unit id="/plural_test:dict/NSStringLocalizedFormatKey:dict/:string">
        <source>%#@format@</source>
        <target>%#@format@</target>
      </trans-unit>
      <trans-unit id="/plural_test:dict/format:dict/few:dict/:string">
        <source>Other</source>
        <target>Немного</target>
      </trans-unit>
      <trans-unit id="/plural_test:dict/format:dict/many:dict/:string">
        <source>Other</source>
        <target>Много</target>
      </trans-unit>
      <trans-unit id="/plural_test:dict/format:dict/one:dict/:string">
        <source>One</source>
        <target>Один</target>
      </trans-unit>
      <trans-unit id="/plural_test:dict/format:dict/other:dict/:string">
        <source>Other</source>
        <target>Другое</target>
      </trans-unit>
    </body>
  </file>

Supported forms are:

zero
one
two
few
many
other

Forms like =0 or =404 will be lost at import.

Handling translation states

Your target tags can contain certain translation states, for example:

<source>source text</source>
<target state="translated">target translation</target>

Lokalise will handle these translation states appropriately, maintaining the integrity of your translation workflow.

XLIFF state	Translation status on Lokalise
translated	Reviewed = false, unverified = false
final, signed-off	Reviewed = true, unverified = false
new	Reviewed = false, unverified = false
needs-translation	Reviewed = false, unverified = true
needs-adaptation	Reviewed = false, unverified = true
needs-l10n	Reviewed = false, unverified = true
needs-review-adaptation	Reviewed = false, unverified = true
needs-review-l10n	Reviewed = false, unverified = true
needs-review-translation	Reviewed = false, unverified = true

Please note that the Reviewed status will become available only if the project admin has enabled the Reviewing feature in the project settings.

Custom attributes

You can easily provide custom attributes for XLIFF translation keys. To achieve that, open key editor and switch to the Custom attributes tab:

Sample data

Here's a sample XLIFF file with English as the source language with 2 plural forms and Arabic as the target language with 6 plural forms:

<!--?xml version="1.0" encoding="UTF-8" ?-->
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" target-language="ar" datatype="plaintext" original="user_section.tmpl">
        <body>
            <trans-unit id="header" datatype="html">
                <source>Hello</source>
                <target> ... </target>
                <context-group purpose="location">
                    <context context-type="sourcefile">app/app.component.ts</context>
                    <context context-type="linenumber">14</context>
                </context-group>
                <note priority="1" from="description">Sample header</note>
                <note priority="1" from="meaning">Welcome visitors</note>
            </trans-unit>
            <trans-unit id="wolves" datatype="html">
                <source>{wolves, plural, one {one} other {wolves}}</source>
                <target>{wolves, plural, zero {...} one {...} two {...} few {...} many {...} other {...}}</target>
            </trans-unit>
        </body>
    </file>
</xliff>

After uploading it to Lokalise its custom attributes will be properly extracted. Here is a full example of custom attributes in JSON with 1 context group and 2 notes:

{
    "datatype": "html",
    "context-groups": [
        {
            "contexts": [
                {
                    "context-type": "sourcefile",
                    "value": "app/app.component.ts"
                },
                {
                    "context-type": "linenumber",
                    "value": "1"
                }
            ],
            "purpose": "location"
        }
    ],
    "notes": [
        {
            "value": "An introduction header for this sample",
            "priority": "1",
            "from": "description"
        },
        {
            "value": "User welcome",
            "priority": "1",
            "from": "meaning"
        }
    ]
}

Working with offline XLIFF

If the Offline translation feature is enabled in the project settings, task assignees can export the assigned items in the XLIFF format to work on them offline. Then, the finalized XLIFF file can be imported back to the assigned task.

To achieve that, open the Tasks page, find the task you are interested in, and click on the Offline XLIFF dropdown:

Special notes

Elements supported

Lokalise supports the most commonly used elements and attributes in XLIFF version 1.2. Non-supported information or elements will not be saved. The context and notes will be saved as custom key attributes along with some other information for the Angular XLIFF format. The supported elements are:

<xliff> Attributes: version.
<file> Attributes: source-language, target-language, original. The original attribute is used as a contextDatatype attribute and is mandatory as per specifications, but our system doesn't save it.
<body>
<trans-unit> Attributes: id, datatype. The datatype is saved as a custom attribute.
<source>
<target>
<context-group> Attributes: purpose.
<context> Attributes: context-type. The custom context-type attribute values will be parsed and saved in the same way as predefined
<note> Attributes: priority, from. Custom priority and from attribute values will be parsed and saved in the same way as predefined

Known limitations

While Lokalise supports adding descriptions and comments via the note tags, it won't update comment for an existing key during XLIFF file reupload (even if the comment in that file has been changed)