XML Localization Interchange File Format (XLIFF) 2.0 is an OASIS standard XML-based format designed to standardize the exchange of localizable data and localization metadata between development environments, Translation Management Systems (TMS), and Computer-Assisted Translation (CAT) tools.

File Extension(s)	.xliff, .xlf, .xml
i18n type(s)	XLIFF_V2

Transifex natively supports XLIFF 2.0 / 2.x (XLIFF_V2), enabling teams using modern web frameworks (such as Symfony, Angular, and Twig), localization pipelines, and enterprise translation tools to upload source strings, manage translations, and automate workflows via the Transifex Web UI, API, CLI, and integrations (e.g., GitHub).

File Format Specification & Structure

1. Root Element & Language Declaration

The root element must specify the XLIFF 2.0 namespace along with the version and language attributes:

srcLang: The IETF language tag for the source language (e.g., en, en-US).
trgLang: (Optional for source-only files) The target language tag (e.g., el, de, fr).

<?xml version="1.0" encoding="UTF-8"?>

<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en" trgLang="el">

  ...

</xliff>

2. File Container (<file>)

Every XLIFF 2.0 document must include at least one <file> element. The <file> tag requires a unique id attribute:

<file id="f1" original="Localizable.strings">

  ...

</file>

3. Translation Units (<unit>) & Segments (<segment>)

Unit Identifier (id): Every <unit> must contain a unique id attribute within the file. An optional name attribute can be provided for human-readable string identifiers.
Segment Wrapper (<segment>): Unlike XLIFF 1.2, <source> and <target> elements in XLIFF 2.0 must be wrapped inside a <segment> container. Placing <source> directly inside <unit> violates the XLIFF 2.0 schema and will cause import validation failures.

<unit id="msg_welcome" name="welcome.greeting">

  <segment>

    <source>Welcome to our application!</source>

    <target>Καλώς ήρθατε στην εφαρμογή μας!</target>

  </segment>

</unit>

Supported Modules & Advanced Features

Developer Notes & Context

Developer comments and contextual guidance are defined using <notes> and <note> elements within the <unit> container:

<unit id="btn_submit">

  <notes>

    <note category="description" priority="1">Button label displayed on the checkout page</note>

  </notes>

  <segment>

    <source>Submit Order</source>

  </segment>

</unit>

String Location & Occurrences (mda:metadata)

Transifex parses source file occurrences and line numbers via the XLIFF 2.0 Metadata module (xmlns:mda="urn:oasis:names:tc:xliff:metadata:2.0"):

<unit id="lbl_confirm">

  <mda:metadata>

    <mda:metaGroup id="po-reference" category="location">

      <mda:meta type="sourcefile">templates/auth/login.html.twig</mda:meta>

      <mda:meta type="linenumber">42</mda:meta>

    </mda:metaGroup>

  </mda:metadata>

  <segment>

    <source>Confirm email address</source>

  </segment>

</unit>

Character Limits & Size Restrictions (slr:sizerestriction)

Character limits are parsed using the Size and Length Restriction module (xmlns:slr="urn:oasis:names:tc:xliff:sizerestriction:2.0"):

<unit id="nav_home" slr:maxRestriction="15" slr:sizeUnit="char">

  <segment>

    <source>Home Page</source>

  </segment>

</unit>

Plural Strings (ICU Syntax)

Pluralized messages formatted with ICU syntax inside the <source> tag are fully supported:

<unit id="trial_expiration">

  <segment>

    <source>{count, plural, one {Your trial ends in 1 day} other {Your trial ends in # days}}</source>

  </segment>

</unit>

Default placeholders

These are the default placeholders that you could have in your file, and they will be recognized:

match: ['%1$s', '%(key1)s', '%s', '%d', '%.2f', '%-5d', '%+2d']

Download modes

The following table summarizes the behavior of XLIFF files for different download modes:

Workflow & Processing Rules

1. ID-Based Format Behavior

XLIFF_V2 operates as an ID-based file format (consistent with the Transifex XLIFF 1.0 ID-based parser).

Strings are uniquely identified in Transifex by their <unit id="..."> within the resource.
Flags exclusive to key-based formats (such as keep_translations and replace_edited_strings) are not applicable to XLIFF_V2.

2. Handling Duplicate Unit IDs

In accordance with the XLIFF 2.0 standard, each <unit> within a <file> must have a unique id. If an uploaded file contains multiple units with identical IDs, Transifex retains the first occurrence and ignores subsequent duplicates during file ingestion.

3. Translation Memory (TM) & Context Matching

Transifex derives string context from the <file id="..."> container and resource attributes while utilizing the unit ID as the key identifier. Strings sharing identical source text within the same file container correctly match Translation Memory (TM) context entries, maximizing translation reuse and autofill accuracy.

4. File Downloads & Export Modes

When exporting translated files via the Web UI, API, or CLI:

Default Download: Returns the complete translated XLIFF 2.0 structure.
Workflow State Filters: Standard download modes such as onlyreviewed and onlyproofread are fully supported to export only translations that have reached specific workflow milestones.
Pseudo-Localization: Generates pseudo-localized strings within the <target> tags of valid XLIFF 2.0 output.

Common Validation Errors & Troubleshooting

Issue / Error	Cause	Solution
Missing <segment> tag	<source> or <target> placed directly under <unit>	Wrap <source> and <target> inside a <segment> container.
Missing id attribute	<unit> or <file> tag lacks an id attribute	Ensure every <file> and <unit> has an explicit id="unique_id".
Unescaped XML entities	Characters such as &, <, or > in <source>	Escape special characters (e.g., use & instead of &).
Legacy XLIFF 1.2 tags	Use of <body>, <trans-unit>, or <bin-unit>	Update markup to XLIFF 2.0 structure (<unit> and <segment>).
Missing <file> container	Document root contains <unit> tags directly	Place <unit> elements inside a parent <file id="..."> tag.

💡Tip

Looking for more help? Get support from our Transifex Community Forum!

Find answers or post to get help from Transifex Support and our Community.