XLIFF Guide for Developers and Localization Managers

Last reviewed: 4 October 2026

Short answer

Use XLIFF as a documented exchange contract, not just an XML attachment. Agree the version, identifiers, notes, protected codes and workflow mapping before export. Translate the intended text while preserving the information needed to rebuild the original resources. Check structure, round-trip preservation and application behavior separately. A schema-valid file can still contain a wrong translation or information the receiving tool ignores.

Key takeaways

Name the XLIFF version and supported profile explicitly.
Keep stable identities connected to the source resource map.
Supply notes that explain actions, states and constraints.
Protect inline data without freezing natural sentence order unnecessarily.
Define who may change review states and when.
Reassemble and test resources before approving a release.

What should the exchange contract define?

The contract should state what information must survive every handoff and how the translated file returns to the product. Include the extraction tool, source revision, target language, supported version and import procedure. Do not rely on the extension alone to establish compatibility.

OASIS defines XLIFF 2.1 for carrying localizable data between process steps.[1] This guide uses that named version for its main example. It does not claim every tool supports it or that a tool's generic XLIFF import preserves every optional feature.

Agree a representative pilot fixture before a large export. Include a button, error, variable, note, changed source and message with meaningful formatting. Ask the receiving tool to return an edited fixture, then compare the information the workflow depends on.

Contract item	Decision to record	Evidence after import
Version and profile	Which document and features are accepted?	Export matches the agreed profile
Source revision	Which resource snapshot was extracted?	Import refers to that snapshot
Identity mapping	How does a unit map back to a resource?	Correct key receives the translation
Context	Which notes and references are required?	Reviewer sees the necessary information
Protected content	Which codes must remain intact?	Original data can be reconstructed
Review state	Which statuses permit release?	Import follows the approved policy
Metadata	Which fields or modules matter?	Required fields remain available
Reassembly	Who rebuilds and tests the output?	Product behavior is checked

Keep this contract near the project handoff so the next person can reproduce it. A change to the exporter or translation tool should trigger a new compatibility check when it can affect those fields.

How do units, segments and IDs relate?

Separate the logical message identity from the segment used to translate part of that message. In the 2.1 example, a unit contains a segment with source and target.[1] The project should keep the connection to its original resource independent of how the editing tool presents the text.

A resource such as quote.received can use a stable extraction mapping. The XLIFF name in the example records that human-readable resource reference, while IDs identify the file, unit and segment. These names are an original project convention, not a rule that every XLIFF exporter must use.

Avoid using the translation text itself as the only reconstruction key. A wording change or duplicate sentence can make that ambiguous. Keep a mapping file or supported source structure when the importer needs it, and confirm how segmentation changes are handled.

Segmentation is not merely visual. If a tool splits a message, reviewers still need enough context to judge the full instruction. Reassembly must respect the source structure and the exchange profile. Do not merge or split units by hand just to make the editor more comfortable.

What does a small protected-variable example look like?

Use an inline code when the workflow needs to protect source data from translation. The following original example stores the application token separately and references it with a placeholder. The target changes the sentence while preserving the protected reference.

<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0"
       version="2.1" srcLang="en" trgLang="vi">
  <file id="f1" original="messages.json">
    <unit id="u1" name="quote.received">
      <notes>
        <note category="description">Shown after a request is accepted. Preserve the request identifier.</note>
      </notes>
      <originalData>
        <data id="d1">{{requestId}}</data>
      </originalData>
      <segment id="s1" state="translated">
        <source>We received request <ph id="p1" dataRef="d1"/>.</source>
        <target>Đã nhận yêu cầu <ph id="p1" dataRef="d1"/>.</target>
      </segment>
    </unit>
  </file>
</xliff>

The namespace is the 2.x core namespace even though the declared document version here is 2.1. Do not rewrite namespaces based on a guess about the file name. Consult the specification and validation artifacts used by the profile.[1]

The protected token is only an illustrative extraction decision. Some pipelines preserve variables in text or use other inline representations. Choose the representation your exporter and importer support, then verify that reassembly returns the exact token expected by the application.

How should notes and metadata help translators?

Provide concise context that changes a translation decision. Explain the screen, the action, the meaning of variables and any constraint the reviewer must respect. A generic note saying “translate accurately” does not resolve an ambiguous word.

For a button, state what happens after activation. For an error, state the cause and the action the customer can take. For a status, identify the event already confirmed by the system. In the example, receiving a request does not promise that the project is accepted commercially or already completed.

Separate essential context from internal chatter. Notes should not contain unnecessary personal data or confidential information unrelated to the task. If screenshots or references are supplied separately, keep their identifiers consistent with the message inventory.

OASIS defines notes and additional modules, including metadata, in the 2.1 specification.[1] Decide which supported features the project actually uses. Do not insert arbitrary unnamespaced fields into the document and assume every tool will understand them. Verify whether required information survives the selected export profile.

How should teams protect inline codes?

Preserve code identity and its original-data relationship while translating the surrounding language. OASIS describes placeholder and paired-code representations with their constraints.[1] The practical review should test both the linguistic placement and the technical reconstruction.

Allow natural reordering where the source contract permits it. A Vietnamese sentence may need a token in a different position. At the same time, paired formatting or linked components can impose boundaries. Explain those constraints instead of telling translators to preserve every character position regardless of meaning.

Check for missing, duplicated or mismatched codes. Confirm the source and target refer to the intended original data, not merely to any identifier that happens to exist. A validator can help catch structural issues, but the business meaning still requires review.

Test the reconstructed resource with realistic values. A long request identifier or a value containing punctuation can reveal a layout or rendering issue not visible in the editor's placeholder view. Keep that product-level test separate from the exchange-file check.

What do segment states mean for approval?

Map states to the team's responsibilities and release policy. XLIFF 2.1 defines initial, translated, reviewed and final segment states.[1] A state label should record real work, not make unfinished content look approved.

State	Project question to answer	Required process evidence
initial	What work is still pending?	Source and context are ready for assignment
translated	Who completed the target text?	Translation delivered against the source revision
reviewed	What kind of review was performed?	Reviewer and findings are recorded
final	What permits this segment to be used?	Project release criteria are satisfied

The right-hand columns are an original governance proposal, not additional normative meanings imposed by the standard. A team's “reviewed” status may concern linguistic review while its interface testing remains separate. State that explicitly so nobody mistakes a translated segment for a tested application.

Protect the workflow during import. If a vendor tool resets states or the application importer ignores them, decide how approval will be enforced elsewhere. Changing every state to final in a text editor does not replace evidence that the required checks occurred.

How do 1.2 and 2.x differences affect a project?

Treat version changes as a conversion task with a tested mapping. XLIFF 1.2 uses structures such as trans-unit; the 2.1 example uses unit and segment.[2][1] Renaming one element does not establish a safe conversion.

Inventory the source document's notes, codes, segmentation and workflow information. Identify how the receiving format represents each required item, and which information may need another supported field or external record. Do not assume a tool's export button preserves the same semantics across versions.

Include actual source samples in a pilot. Compare the reconstructed application resources, not just the two exchange documents. If a legacy system requires 1.2, record that requirement rather than sending a 2.x document that happens to have a familiar extension.

Avoid calling one version universally superior for all projects. The useful choice is the agreed profile that works with the product and receiving tools. Migration may be appropriate, but its cost and preservation requirements should be visible in the scope.

Which QA checks should come before release?

Check XML structure, XLIFF requirements, information preservation and reconstructed behavior in layers. XML well-formedness and schema validity are distinct concepts in W3C's XML framework.[3] Neither proves that the translation answers the customer's task correctly.

Check	Practical test	Acceptance evidence
Well-formed XML	Parse the exported file	No structural parse error
Agreed profile	Validate with applicable artifacts	Required rules pass or exceptions are resolved
Identity	Compare file, unit and resource mapping	Translation returns to the intended resource
Languages	Review source and target declarations	They match the content and project
Codes	Compare protected references	No unauthorized loss or duplication
Context	Export and re-import required notes	Reviewer still has essential information
Workflow	Inspect states before and after handoff	Release policy remains enforceable
Product behavior	Build and exercise representative messages	Meaning, data and interface work together

Save the fixture and results with the tool versions. A future update can then be checked against a known example. Add new edge cases when the product introduces a new kind of message or formatting; do not merely rerun a button-only fixture forever.

How should a localization manager organize the handoff?

Give each handoff a clear source revision, owner and acceptance boundary. Separate translation delivery, linguistic review, conversion verification and application testing when different people perform them. The release record should say which work has actually happened.

LocalizeZone recommends including the XLIFF sample, originating resource format and importer details in the software localization brief. Send representative screenshots and known unsupported features through the quotation page. Specify whether the request includes exchange-file QA or testing in a runnable product.

Agree how queries are resolved. A translator unsure whether a label is an action or a status should receive an answer that is recorded for similar messages. A developer investigating a missing code needs the unit and source mapping. Keep both kinds of feedback connected to the same resource identity.

FAQ

Is XLIFF a replacement for the application's resources?

Not automatically. It may be an exchange step. The importer must reconstruct the resource structure the application actually consumes.

Can I change IDs while translating?

Do not change protected identities without an agreed migration. IDs and mappings may be necessary to return the target to the right message.

Should every translated segment be final?

No. Follow the agreed approval policy and record the work performed. A final label cannot substitute for missing review or application checks.

Does XML parsing validate every XLIFF requirement?

No. Parsing checks well-formedness. Use applicable schema and other validation rules, then review preservation and product behavior separately.

Can 1.2 be converted by renaming trans-unit?

No. Compare structures, codes, context and workflow semantics. Test the conversion and resource reconstruction using representative files.

What should we provide for a project estimate?

Provide sample XLIFF, version and profile, source resources, source revision, screenshots and import workflow. Explain the required review and release checks.

Sources and methodology

OASIS 2.1 and 1.2 specifications and W3C XML guidance were checked on 4 October 2026. The protected-variable document, contract matrix and process tables are original examples. Local validation of a small example is narrower than full conformance or cross-vendor interoperability; this guide does not report a vendor round trip, product build or production-language review.

References

[1] OASIS. XLIFF Version 2.1, OASIS Standard, 13 February 2018.

[2] OASIS. XLIFF Version 1.2, OASIS Standard, 1 February 2008.

[3] W3C. Extensible Markup Language 1.0, Fifth Edition.

XLIFF Localization Guide for Developers and Localization Managers