XLIFF file

XLIFF (XML Localization Interchange File Format) is an XML-based file format that is widely used in the fields of translation and localization. It is created to simplify the exchange of localizable data and allow interoperability between different tools during the localization process.

The XLIFF files usually have the xliff or xlf extension. Both extensions are fully valid, and there is no difference between such files in terms of functionality and content.

What characterizes XLIFF files is that they are usually bilingual. That means that these files contain pairs of the source text and the translation. However, in some cases, these files can have only the source text, and as such, they are still valid and represent template files for localization.

The XLIFF file specification has evolved since its inception. Therefore, there are several versions of this file today. The two most commonly used versions are 1.2 and 2.0. Although these two versions have a lot in common, they are not compatible.

The XLIFF 1.2 is the most commonly used version of XLIFF files. Although made a long time ago, a large number of frameworks still base their localization on this format.

Note: Since XLIFF files are quite flexible and syntax in the messages can be versatile, all examples in this document are from the Angular. However, other frameworks and localization tools will most likely use a similar syntax in messages.

XLIFF file example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en" target-language="fr" datatype="plaintext" original="ng2.template">
    <header>
      <tool tool-id="localizely.com" tool-name="Localizely"/>
    </header>
    <body>
      <trans-unit id="common.welcome">
        <source>Welcome!</source>
        <target>Bienvenue!</target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">16</context>
        </context-group>
      </trans-unit>
      <trans-unit id="common.app.title">
        <source>Diary</source>
        <target>Agenda</target>
        <context-group purpose="location">
          <context context-type="sourcefile">src/app/app.component.html</context>
          <context context-type="linenumber">4</context>
        </context-group>
        <note priority="1" from="description">App title</note>
      </trans-unit>
    </body>
  </file>
</xliff>

XLIFF file structure

The best way to explain the structure of the XLIFF file is through the list of its base elements. Below is one such list that contains a brief description of the most commonly used elements and attributes.

xliff
- This element represents the XLIFF document. It is composed of one or more file elements.
- Attributes:
  - version – specifies the version of XLIFF.
file
- This element represents the original document from which the content is derived. It is composed of an optional header element, followed by a body element.
- Attributes:
  - original – specifies the name of the original file.
  - datatype – specifies the kind of text contained in the element (e.g. plaintext).
  - source-language – specifies the language for the source elements.
  - target-language (optional) – specifies the language for the target elements.
header
- This element contains the metadata of the file element. It is usually composed of zero or more note and tool elements.
tool
- This element describes the tool that has been used to execute a given task in the document.
- Attributes:
  - tool-id – represents unique identifier of a given tool.
  - tool-name – specifies the name of a given tool.
body
- This element contains the localizable content from the file. It is usually composed of zero or more group and trans-unit elements.
group
- This element specifies a set of elements that should be processed together. It is usually composed of zero or more note, group, and trans-unit elements.
trans-unit
- This element represents a translation unit. It is composed of source and target elements.
- Attributes:
  - id – represents the identifier.
  - approved (optional) – indicates whether a translation is approved during the review phase.
  - translate (optional) – indicates whether it should be translated.
  - resname (optional) – represents the resource name (e.g. string key).
  - minwidth (optional) – represents the minimum width of the translation.
  - maxwidth (optional) – represents the maximum width of the translation.
source
- This element represents the content that needs to be translated (i.e. source text).
target
- This element represents translation of the source text (i.e. target text).
context-group
- This element holds context data. It is composed of one or more context elements.
- Attributes:
  - name (optional) – specifies the user-defined name of the element.
  - purpose (optional) – specifies the purpose of the element (e.g. location, information, ...).
context
- This element describes the context of the source text.
- Attributes:
  - context-type – specifies the context type (e.g. sourcefile, linenumber, ...).
note
- This element represents the localization-related comments (e.g. instructions from the developers).
- Attributes:
  - from (optional) – indicates the author of a note.
  - priority (optional) – specifies the priority of a note (a number between 1 and 10, 1 represents the highest priority).
x
- This element represents the generic placeholder.
- Attributes:
  - id – represents the identifier.
  - equiv-text (optional) – indicates the equivalent text to substitute in place of an inline tag.

ICU message syntax

Below you can find examples of ICU message syntax in the XLIFF files.

Plural

<trans-unit id="message.plural" datatype="html">
  <source>{VAR_PLURAL, plural, one {<x id="INTERPOLATION"/> item} other {<x id="INTERPOLATION"/> items}}</source>
  <target>{VAR_PLURAL, plural, one {<x id="INTERPOLATION"/> article} other {<x id="INTERPOLATION"/> articles}}</target>
</trans-unit>

See the language plural rules page for more details.

Select

<trans-unit id="message.gender" datatype="html">
  <source>{VAR_SELECT, select, male {Mr <x id="INTERPOLATION"/>} female {Mrs <x id="INTERPOLATION"/>} other {Client <x id="INTERPOLATION"/>}}</source>
  <target>{VAR_SELECT, select, male {Monsieur <x id="INTERPOLATION"/>} female {Mme <x id="INTERPOLATION"/>} other {Cliente <x id="INTERPOLATION"/>}}</target>
</trans-unit>

Number format

<trans-unit id="message.number-format" datatype="html">
  <source>Formatted number: <x id="INTERPOLATION" equiv-text="{{ amount | number: &quot;.2&quot; }}"/></source>
  <target>Numéro formaté: <x id="INTERPOLATION" equiv-text="{{ amount | number: &quot;.2&quot; }}"/></target>
</trans-unit>

Date format

<trans-unit id="message.date-format" datatype="html">
  <source>Formatted date: <x id="INTERPOLATION" equiv-text="{{ currentDate | date: &quot;fullDate&quot; }}"/></source>
  <target>Date formatée: <x id="INTERPOLATION" equiv-text="{{ currentDate | date: &quot;fullDate&quot; }}"/></target>
</trans-unit>

The XLIFF 2.0, although young, is quite a popular format in localization. Compared to XLIFF 1.2, XLIFF 2.0 has a simpler and better-organized document structure. However, it is still not so widely supported.

XLIFF file example

<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en" trgLang="fr">
  <file id="ngi18n" original="ng.template">
    <unit id="common.welcome">
      <notes>
        <note category="location">src/app/app.component.html:16</note>
      </notes>
      <segment>
        <source>Welcome!</source>
        <target>Bienvenue!</target>
      </segment>
    </unit>
    <unit id="common.app.title">
      <notes>
        <note category="location">src/app/app.component.html:4</note>
        <note category="description">App title</note>
      </notes>
      <segment>
        <source>Diary</source>
        <target>Agenda</target>
      </segment>
    </unit>
  </file>
</xliff>

XLIFF file structure

xliff
- This element represents the XLIFF document. It is composed of one or more file elements.
- Attributes:
  - version – specifies the version of XLIFF.
  - srcLang – represents the language code of the source text.
  - trgLang (optional) – represents the language code of the target text.
file
- This element represents the container for localization material extracted from the document. It is composed of optional notes element, followed by one or more unit and group elements.
- Attributes:
  - id – specifies the identifier of the given element.
  - original (optional) – specifies the original file (e.g. a pointer to the location of the original document).
group
- This element provides a way to organize units into a structured hierarchy. It is composed of optional notes element, followed by zero or more unit and group elements.
- Attributes:
  - id – specifies the identifier of the given element.
unit
- This element represents a container for the elements that hold source and translation texts and additional notes as well. It is composed of optional notes element and one or more segment elements.
- Attributes:
  - id – specifies the identifier of the given element.
notes
- This element represents the collection of comments. It is composed of one or more note elements.
note
- This element represents the user comments and notes.
- Attributes:
  - category (optional) – provides a way to categorize the note.
  - priority (optional) – provides a way to prioritize the note (a number between 1 and 10, 1 represents the highest priority).
segment
- This element represents a container that holds elements with source and translation texts. It is composed of source element and of optional target element.
- Attributes:
  - state (optional) – indicates the state of the translation.
source
- This element holds the text that needs to be translated.
target
- This element holds the translation of the source text.
ph
- This element represents a standalone code (placeholder).
- Attributes:
  - id – specifies the identifier of the given element.
  - equiv (optional) – represents the equivalent text.
  - disp (optional) – represents the display text.

ICU message syntax

Below you can find examples of ICU message syntax in the XLIFF files.

Plural

<unit id="message.plural">
  <segment>
    <source>{VAR_PLURAL, plural, one {<ph id="0" equiv="INTERPOLATION"/> item} other {<ph id="1" equiv="INTERPOLATION"/> items}}</source>
    <target>{VAR_PLURAL, plural, one {<ph id="0" equiv="INTERPOLATION"/> article} other {<ph id="1" equiv="INTERPOLATION"/> articles}}</target>
  </segment>
</unit>

See the language plural rules page for more details.

Select

<unit id="message.gender">
  <segment>
    <source>{VAR_SELECT, select, male {Mr <ph id="0" equiv="INTERPOLATION"/>} female {Mrs <ph id="1" equiv="INTERPOLATION"/>} other {Client <ph id="2" equiv="INTERPOLATION"/>}}</source>
    <target>{VAR_SELECT, select, male {Monsieur <ph id="0" equiv="INTERPOLATION"/>} female {Mme <ph id="1" equiv="INTERPOLATION"/>} other {Cliente <ph id="2" equiv="INTERPOLATION"/>}}</target>
  </segment>
</unit>

Number format

<unit id="message.number-format">
  <segment>
    <source>Formatted number: <ph id="0" equiv="INTERPOLATION" disp="{{ amount | number: &quot;.2&quot; }}"/></source>
    <target>Numéro formaté: <ph id="0" equiv="INTERPOLATION" disp="{{ amount | number: &quot;.2&quot; }}"/></target>
  </segment>
</unit>

Date format

<unit id="message.date-format">
  <segment>
    <source>Formatted date: <ph id="0" equiv="INTERPOLATION" disp="{{ currentDate | date: &quot;fullDate&quot; }}"/></source>
    <target>Date formatée: <ph id="0" equiv="INTERPOLATION" disp="{{ currentDate | date: &quot;fullDate&quot; }}"/></target>
  </segment>
</unit>

How to create XLIFF files?

The XLIFF files are usually generated by tools. However, since they are basically XML files, they can also be created manually.

How to edit XLIFF files?

Since XLIFF files can be opened in any editor that supports XML, their editing by hand is very easy. However, it is recommended to use specially designed tools for XLIFF files to avoid potential syntax and structural errors.

How to validate XLIFF files?

Validation of XLIFF files is quite similar to validation of XML files. In general, any tool that supports XLIFF files could be helpful. The most common validation errors are typos, invalid file structure, missing closing elements, and similar.

Previous: Supported file formats

Tired of manually editing translation files?

Our platform streamlines software localization for you.

Try now for Free

XLIFF file

Documentation

XLIFF file example

XLIFF file structure

ICU message syntax

Plural

Select

Number format

Date format

XLIFF file example

XLIFF file structure

ICU message syntax

Plural

Select

Number format

Date format

How to create XLIFF files?

How to edit XLIFF files?

How to validate XLIFF files?

Documentation

About

Resources

Free tools

Boring stuff

Newsletter