Work with MXLIFF files - Phrase Developer Hub

What is MXLIFF?

MXLIFF (Memsource XLIFF) is Phrase’s bilingual file format. It’s based on XLIFF 1.2 with an added m: namespace that carries Phrase-specific segment and job metadata: translation memory (TM) and machine translation (MT) matches, confirmation and lock state, tag metadata, custom field values, and more. MXLIFF is the format used to move translation content into and out of Phrase TMS (Translation Management System) jobs for editing outside the platform, and to feed translated content back into a translation memory. For a product-level introduction, see the MXLIFF Files (TMS) support article. This guide documents the format itself for developers who generate, parse, or round-trip MXLIFF programmatically, and gives the full element and attribute reference under MXLIFF structure below.

When to use it

Reach for MXLIFF when you need to:

Export a job’s segments (source, target, TM/MT matches, confirmation and lock state) for editing with an external tool
Re-import edited segments back into a job
Store translations from a bilingual file into a translation memory

Working with MXLIFF via the API

Task	API operation
Export a job as a bilingual MXLIFF file	Download bilingual file
Import a bilingual MXLIFF file into a job	Upload bilingual file
Store translations from an MXLIFF file into a translation memory	Import translation memory

The same actions are available from the Phrase TMS web UI: Project → Jobs → Select job(s) → Download → Bilingual MXLIFF to export, and Project → Jobs → Tools → Upload → Select MXLIFF to import.

MXLIFF structure

This section documents the parts of the MXLIFF format that are specific to Phrase. It also mentions the values used for standard XLIFF elements/attributes where that’s relevant. For everything not covered here, MXLIFF follows the XLIFF 1.2 specification.

Element tree

<xliff>
  <file>
    <header>
      <note>
      <metadata-schema>
        <m:fields> (schema)
          <m:field>
            <m:name>
      <m:in-ctx-preview-skel>
    <body>
      <group>
        <m:prop>
          <m:target-order>
        <m:in-ctx-preview-metadata>
          <m:mark>
            <m:open-mark-content>
            <m:close-mark-content>
        <trans-unit>
          <m:comment>
          <m:latest-trans-props>
            <m:trans-prop>
          <m:tunit-metadata>
            <m:mark>
              <m:type>
              <m:content>
              <m:trans-attributes>
          <m:tunit-target-metadata>
            (same shape as m:tunit-metadata)
          <m:editing-stats>
            <m:editing-time>
            <m:thinking-time>
          <m:annotations>
            <m:annotation>
              <m:text>
          <m:metadata>
            <m:fields> (values)
              <m:field>
                <m:value>
  <m:extra>
    <m:users>
      <m:user>

`<xliff>`

The Phrase namespace is added with prefix m and URI http://www.memsource.com/mxlf/2.0. Attributes:

version: version of the underlying XLIFF format, always 1.2.
m:version: MXLIFF schema version. New optional elements and attributes are occasionally added as the version increments; unrecognized elements/attributes should be ignored rather than treated as errors.
m:level: number representing a workflow level.

<xliff
  xmlns="urn:oasis:names:tc:xliff:document:1.2"
  xmlns:m="http://www.memsource.com/mxlf/2.0"
  version="1.2"
  m:version="2.12"
  m:level="3"
>

`<file>`

Attributes:

datatype: x-undefined.
m:file-format: format of the original file used during import.
m:task-id: identifies the task this file belongs to. There is a 1:1 relationship between a job and a task.
m:begin-group-id: ID of the first segment (0-indexed) included in the file.
m:end-group-id: ID of the last segment included in the file.
m:transmem-ignore-tag-metadata: whether tag metadata was ignored for translation memory matching. Values: yes, no.

<file
  original="messages.json"
  source-language="en"
  target-language="sk"
  datatype="x-undefined"
  m:task-id="aB2cd4eF_dc2"
  m:begin-group-id="0"
  m:end-group-id="4"
  m:transmem-ignore-tag-metadata="yes"
>

Contains:

Zero or more <note> elements
Zero or one <m:metadata-schema> element
Zero or one <m:in-ctx-preview-skel> element

`<note>`

Attributes:

m:id: ID of a note, unique within the same m:origin.
m:category: categorization of a note.
m:origin: path in the original file the note was extracted from; corresponds to x-file-part (see <group>).

`<m:metadata-schema>`

Describes the schema of all segment-level metadata. Contains one <m:fields> element. <m:fields> (schema): contains one or more <m:field> elements, each representing a single custom field. <m:field> attributes:

id: ID of the metadata field definition.
type: one of text, date, boolean, link, number, select, multi.

Each <m:field> contains one <m:name> element with the field’s display name.

`<m:in-ctx-preview-skel>`

Skeleton for the in-context preview shown in editors. Contains segment placeholders like <span id="m-tgroup_1" class="m-tgroup"></span>, which editors replace with metadata from <m:in-ctx-preview-metadata> and text from <source>/<target>. Attributes:

bilingual: whether the job is bilingual (true) or monolingual (false).
skel-omitted: true if the in-context preview is not included.
size: length in bytes of the skeleton, set when it’s omitted.

Contains zero or one embedded HTML document written as CDATA.

<!-- In-context preview generated -->
<in-ctx-preview-skel bilingual="false"><![CDATA[
<html>
<h1><span id="m-tgroup_0" class="m-tgroup"></span></h1>
<span id="m-tgroup_1" class="m-tgroup"></span>
<ul>
    <li><span id="m-tgroup_2" class="m-tgroup"></span></li>
    <li><span id="m-tgroup_3" class="m-tgroup"></span></li>
</ul>
</html>
]]></in-ctx-preview-skel>

<!-- In-context preview skipped -->
<in-ctx-preview-skel bilingual="true" skel-omitted="true" size="328" />

`<group>`

Attributes:

m:para-id: identifies a paragraph.

Contains:

Zero or one <context-group> element without a name attribute, holding general context information:
- x-file-part: part of the original file the segment was extracted from
- x-key: context key
- x-key-note: context note
- x-max-len: maximum allowed length of a translation
Zero or one <context-group> element with name="x-plural", holding plural information for PO (gettext) files:
- x-plural-category: plural rule category (zero, one, two, few, many, other, or a concrete number)
- x-plural-examples: sample values for the category
- x-plural-source-singular / x-plural-source-plural: source text in singular/plural form
Zero or one <m:prop> element
Zero or one <m:in-ctx-preview-metadata> element

<!-- General group context -->
<context-group>
  <context context-type="x-file-part">document::variables</context>
  <context context-type="x-key">variable.id.36</context>
  <context context-type="x-key-note">References specific product type</context>
  <context context-type="x-max-len">30</context>
</context-group>

<!-- PO plural context -->
<context-group name="x-plural">
  <context context-type="x-plural-category">other</context>
  <context context-type="x-plural-examples">0, 5~∞</context>
  <context context-type="x-plural-source-singular">I've bought a new chair.</context>
  <context context-type="x-plural-source-plural">I've bought some new chairs.</context>
</context-group>

`<m:prop>`

Group properties. Contains zero or one <m:target-order> element, a number indicating the order in which to compose target segments (equivalent to Segments order in XLIFF 2.0).

`<m:in-ctx-preview-metadata>`

Metadata for the in-context preview skeleton, specific to the parent <group>. Contains zero or more <m:mark> elements, each with an id and optional <m:open-mark-content> / <m:close-mark-content> text elements.

<m:in-ctx-preview-metadata>
  <m:mark id="3">
    <m:open-mark-content><![CDATA[<a href="#">]]></m:open-mark-content>
    <m:close-mark-content><![CDATA[</a>]]></m:close-mark-content>
  </m:mark>
</m:in-ctx-preview-metadata>

`<trans-unit>`

Attributes:

xml:space: preserve
m:score: score of an automatically filled translation (e.g. during pre-translation). When m:trans-origin is mt, this is a quality performance score (QPS).
m:gross-score: same as m:score before penalization. Only differs from m:score for translation memory matches.
m:trans-origin: origin of the filled translation: mt (machine translation), tm (translation memory), nt (non-translatable), or rb (deprecated, superseded by nt).
m:trans-origin-detail: detail about the origin, e.g. the specific engine used.
m:confirmed: workflow level at which the segment is confirmed.
m:locked: whether the segment is locked/editable. Values: true, false.
m:locked-by: what locked the segment.
m:locked-by-detail: detail when locked-by is ex.
m:para-id: paragraph ID, matching m:para-id on the parent <group>.
m:repetition-exception: true when a linguist unmarked the segment as a repetition.
m:created-at / m:created-by: when and by whom the segment was created.
m:modified-at / m:modified-by: when and by whom the segment was last modified.
m:level-edited: legacy attribute, always false.

Contains:

Two <alt-trans> elements, distinguished by origin:
- machine-trans: match-quality (MT quality score), m:mt-id (MT connector ID), <target> (MT-provided translation)
- memsource-tm: match-quality (TM match score), tm-id (translation memory ID, if known), <target> (TM-provided translation)
Zero or one <context-group name="sub-trans-unit" purpose="information">, holding metadata about sub-units (segments nested within another segment):
- x-type: type of sub-unit (currently only ICU)
- x-subtype: more granular type, e.g. the ICU variable type
- x-category: differentiates sub-units belonging to the same segment and tag (for ICU, the plural variable form)
- x-parent-trans-unit: ID of the parent <trans-unit>
- x-parent-mark-id: ID of the parent mark
- x-examples: sample values (used for ICU plural variables)
Zero or one <context-group name="context-key" purpose="match">, holding a context key used when a <group> contains multiple <trans-unit> elements in a hierarchy:
- x-key: the segment’s context key
Zero or one <m:latest-trans-props> element
Zero or one <m:tunit-metadata> element
Zero or one <m:tunit-target-metadata> element
Zero or one <m:editing-stats> element
Zero or one <m:annotations> element
Zero or one <m:metadata> element

<!-- Sub-unit metadata -->
<context-group name="sub-trans-unit" purpose="information">
  <context context-type="x-type">icu</context>
  <context context-type="x-subtype">plural</context>
  <context context-type="x-category">few</context>
  <context context-type="x-parent-trans-unit">aB2cd4eF_dc2:1:5</context>
  <context context-type="x-parent-mark-id">3</context>
  <context context-type="x-examples">2~4</context>
</context-group>

<!-- Context key -->
<context-group name="context-key" purpose="match">
  <context context-type="x-key">string.id.29:I bought {p, plural, one {:} other {some books}}.</context>
</context-group>

`<m:comment>`

Deprecated: no longer written or read since converter version 25.8. Historically held a single segment comment (not the same as editor comment functionality), such as extraction details. Attributes: created-at, created-by, modified-at, modified-by, resolved (true/false).

`<m:latest-trans-props>`

Metadata of the latest translation selected in an editor. Contains <m:trans-prop> elements with a name attribute:

score: same as m:score
gross-score: same as m:gross-score
origin: same as m:trans-origin
origin-detail: same as m:trans-origin-detail
processed-by: whether the segment was last processed by an AI service such as MT Optimize or Auto Adapt
target-quality: QPS score from MT Optimize or a third-party service, in the range 0.0 to 1.0

<m:latest-trans-props>
  <m:trans-prop name="score">0.89</m:trans-prop>
  <m:trans-prop name="gross-score">0.94</m:trans-prop>
  <m:trans-prop name="origin">tm</m:trans-prop>
  <m:trans-prop name="origin-detail">2936</m:trans-prop>
  <m:trans-prop name="processed-by">auto-adapt</m:trans-prop>
  <m:trans-prop name="target-quality">0.85</m:trans-prop>
</m:latest-trans-props>

`<m:tunit-metadata>`

Metadata for marks inside <source>, encoded as {1} or {2>translatable<2}. Contains zero or more <m:mark> elements, each with an id and:

<m:type>: type of the mark
<m:content>: the mark’s content
<m:trans-attributes>: comma-separated list of translatable attributes, each following in a subsequent <m:mark> under the same <m:tunit-metadata>

<m:tunit-metadata>
  <m:mark id="1">
    <m:type>b</m:type>
    <m:content>&lt;b&gt;</m:content>
  </m:mark>
  <m:mark id="2">
    <m:type>img</m:type>
    <m:content>&lt;img alt="" src="logo.png"/&gt;</m:content>
    <m:trans-attributes>alt</m:trans-attributes>
  </m:mark>
  <m:mark id="3">
    <m:type>attribute</m:type>
    <m:content>alt</m:content>
  </m:mark>
</m:tunit-metadata>

`<m:tunit-target-metadata>`

Same shape as <m:tunit-metadata>, but describes marks inside <target> instead of <source>.

`<m:editing-stats>`

Editing statistics for a segment. Contains one <m:editing-time> and one <m:thinking-time> element (both numbers, in the same unit). How the times are tracked:

When a user clicks into a segment, both thinking time and editing time start counting.
When the user starts editing, thinking time stops but editing time continues.
When the user clicks into a different segment, editing time stops.
Re-entering a segment resumes counting and adds to the previous totals; if re-entering results in no edits, the times are left unchanged even if the segment is re-confirmed.

`<m:annotations>`

Contains one or more <m:annotation> elements. Attributes:

category: currently only LIONBRIDGE is used.
type: optional, more specific annotation type.
translate: whether the annotated text is translatable (yes/no).
excludeFromCharCount: whether to exclude the text from word/character counts (yes/no).
offset: offset into <source> where the annotation starts.
position: 1-indexed order of the annotated text within <source>.

Contains one <m:text> element with the annotated text.

<m:annotations>
  <m:annotation category="LIONBRIDGE" translate="yes" excludeFromCharCount="no" offset="4" position="1" type="term">
    <m:text>linguist</m:text>
  </m:annotation>
  <m:annotation category="LIONBRIDGE" translate="no" excludeFromCharCount="yes" offset="10" position="2">
    <m:text>Phrase</m:text>
  </m:annotation>
</m:annotations>

`<m:metadata>`

Custom metadata values for a segment. Contains one <m:fields> element. <m:fields> (values): one or more <m:field> elements, each with an rid attribute referencing the corresponding field in <m:metadata-schema>. A field’s value is either plain text, or one or more <m:value> elements when the field type is multi.

`<m:extra>`

Additional information about the whole MXLIFF document. Contains one <m:users> element, which lists every user (via <m:user id="...">) who created or modified any task included in the file.

​What is MXLIFF?

​When to use it

​Working with MXLIFF via the API

​MXLIFF structure

​Element tree

​<xliff>

​<file>

​<header>

​<note>

​<m:metadata-schema>

​<m:in-ctx-preview-skel>

​<group>

​<m:prop>

​<m:in-ctx-preview-metadata>

​<trans-unit>

​<m:comment>

​<m:latest-trans-props>

​<m:tunit-metadata>

​<m:tunit-target-metadata>

​<m:editing-stats>

​<m:annotations>

​<m:metadata>

​<m:extra>

What is MXLIFF?

When to use it

Working with MXLIFF via the API

MXLIFF structure

Element tree

`<xliff>`

`<file>`

`<header>`

`<note>`

`<m:metadata-schema>`

`<m:in-ctx-preview-skel>`

`<group>`

`<m:prop>`

`<m:in-ctx-preview-metadata>`

`<trans-unit>`

`<m:comment>`

`<m:latest-trans-props>`

`<m:tunit-metadata>`

`<m:tunit-target-metadata>`

`<m:editing-stats>`

`<m:annotations>`

`<m:metadata>`

`<m:extra>`