XLIFF Guide for Localization Engineers: Workflow and Validation

A translation can be linguistically correct and still break a release: a placeholder disappears, a button label lands in the wrong screen, or a tool returns a file the build cannot merge. XLIFF gives localization engineers a structured handoff, but it doesn’t make those risks disappear by itself.

What XLIFF is and what it carries¶

XLIFF is an XML vocabulary for storing localizable data and carrying it through localization stages while helping different tools exchange that data. The format separates content from many details of the source file, so a translator can work on text without editing the application’s native resource format directly. The OASIS XLIFF 2.2 specification describes that purpose.

According to the OASIS XLIFF Technical Committee:

“XLIFF is an XML vocabulary that is intended to store localizable data and carry it from one step of the localization process to the other, while allowing interoperability between and among tools.”

In practical terms, XLIFF is a handoff format, not a translation engine. A parser extracts text from a native file, a CAT tool (computer-assisted translation software) presents the extract to a translator, and a build or localization pipeline returns the translated content to the application. The format describes the content and its relationships; your surrounding tools still need to preserve the right context and process the file correctly.

The XLIFF specification describes the format primarily as lossless interchange. Lossless means the transfer should preserve relevant information rather than flattening the content into plain text and throwing away metadata. The specification doesn’t encourage, discourage, or prohibit using XLIFF as a processing format, so a team can use it inside a pipeline if the implementation meets its needs. The OASIS FAQ also describes XLIFF as tool-neutral, extensible, and formalized through XML and a schema.

A typical XLIFF file carries some combination of:

• Source and target language information.
• One or more files or resource groups.
• Units that represent translatable content.
• Source text and, where available, target text.
• Inline codes for placeholders, markup, or other protected content.
• Notes and metadata that help explain usage.
• States or workflow information used by the processing tools.

Names for these pieces differ across versions. A simplified XLIFF 2.0 example in Microsoft’s localization file-format documentation uses an xliff root, language attributes, file, unit, segment, source, and target elements. Treat that example as an illustration of XLIFF 2.0 structure, not as a template for every XLIFF version.

For engineers, the useful mental model is a contract between stages. The extractor promises to identify localizable content and represent it consistently. The CAT tool promises to preserve the parts it doesn’t translate. The merger promises to put the targets back in the expected places. A valid XML file can still violate that contract if the wrong content was extracted or the wrong target was merged.

How extraction, translation, and merging work¶

XLIFF is usually one part of a pipeline that starts and ends with a native resource format. The parser or filter must understand that original format before it can safely identify what should become translatable content. Microsoft’s resource-exchange guide describes the general flow: extract content into XLIFF, translate target segments, then use skeleton files to reassemble the original format.

A skeleton is the source structure or supporting data that stays outside the editable translation content. The exact representation depends on the tools and workflow. Keeping the native structure separate helps protect code and layout, while XLIFF carries the text and metadata that localization teams need to work on.

A practical roundtrip has these stages:

1. Parse the native file. A filter reads the source format and identifies translatable text, protected values, markup, and other relevant structure. The parser must understand the format: a tool that reads HTML doesn’t automatically know how to interpret every application resource file.
2. Extract units. The pipeline writes localizable strings into XLIFF units. Each unit needs a stable identity and enough context to distinguish it from similar text elsewhere.
3. Add context and constraints. Notes, inline codes, identifiers, and language metadata explain how the translator should handle each unit. Source-only information can be carried alongside the XLIFF or in the skeleton.
4. Translate target content. A CAT tool or another process writes target text while preserving structural elements and protected content.
5. Validate the interchange file. The pipeline checks XML syntax, the correct schema and version, plus content-specific rules that the schema can’t catch.
6. Merge into the native format. The merger maps target text back to the appropriate resources and restores the source structure.
7. Preview and test the localized output. Engineers inspect the actual application or document because string length, fonts, directionality, pagination, and wrapping can change the result.

Microsoft’s resource-exchange documentation puts the format’s role this way:

“XLIFF is a file format that can be used when translating source files regardless of what proprietary format they might use.”

That doesn’t mean a single XLIFF parser can read every proprietary source format. The native-format parser is still essential. Microsoft lists examples of formats CAT tools may parse, including HTML, markup, RESX, RTF, Office formats, InDesign, FrameMaker, and plain text. Actual support depends on the parser and tool. An engineer should test the exact source format and the project’s features, not infer support from the fact that a tool can import XLIFF.

A small XLIFF unit, conceptually¶

The structural idea is easier to see in a short conceptual example:

<unit id="checkout.submit">
  <segment>
    <source>Place order</source>
    <target>Place order</target>
  </segment>
</unit>

The example shows a unit ID and a source-target pair. Real files include version-specific structure and may include language declarations, notes, codes, and other metadata. Don’t copy the fragment into a project and assume it is valid for your chosen version: use the relevant specification and schema.

A unit is not necessarily the same as a sentence. One string may be a complete sentence, a short label, or a message with inline variables. The extraction rules determine what gets grouped together. Microsoft’s localization file-format documentation notes a tradeoff: larger units can give translators more useful context and support more idiomatic wording, while excessively long units reduce the chance of a complete translation-memory match.

That tradeoff matters in UI localization. If an extractor splits every phrase into fragments, translators may not know which words belong together. If it combines a whole screen into one enormous unit, reuse and review become harder. The right unit boundary depends on the content and how the application displays it.

For a concrete case, consider a button labeled “Save” and a message that says “Changes saved.” The same English word can have different grammatical forms or meanings across target languages. A developer who assigns one shared key to both contexts makes the translator guess whether the source refers to an action or a completed event. A descriptive ID such as settings.save_button and a separate ID such as settings.changes_saved_message make the roles visible. Mozilla’s developer localization guidance recommends descriptive, unique identifiers tied to the message and its interface role, and cautions against reusing strings across different contexts.

What a roundtrip test should prove¶

A roundtrip test should prove more than “the file imported.” Start with a representative native resource, extract it, run it through the target CAT tool, export the XLIFF, and merge the result. Then compare the localized output with the expected resource structure.

Check that:

• Every intended source unit appears once, unless the extraction rules explicitly require otherwise.
• Each target maps back to the correct source ID.
• Placeholders and inline codes remain present and in valid positions.
• Notes and custom metadata survive import and export where the workflow depends on them.
• The merger handles empty targets, untranslated units, and target-language changes as intended.
• The original native file’s non-localizable content remains intact.

A roundtrip can fail even when each stage reports success. For example, a tool may import a custom extension but omit it on export; the XML remains valid, yet the pipeline loses information. The XLIFF 2.1 specification says processors aren’t required to understand non-XLIFF extension elements or attributes. Conformant applications should preserve extensions when possible under the conditions in the specification, but teams still need to verify their own tool chain. See the XLIFF 2.1 specification.

Choosing between XLIFF 1.2, 2.1, and 2.2¶

Version choice is an interoperability decision. The newest specification isn’t automatically the best fit if one essential tool only supports an older version or ignores a module the project needs.

The dates and version details in the table come from the OASIS XLIFF 1.2 specification, the XLIFF 2.1 specification, and the XLIFF 2.2 Core specification.

XLIFF 1.2 uses a different namespace from the 2.x family, so a tool that supports one doesn’t automatically support the other. The 1.2 specification also has Transitional and Strict schema variants and says users must choose the appropriate schema to validate a document. A version label in a project setting isn’t enough: confirm the namespace and schema actually present in the files.

XLIFF 2.1 requires conformant documents to be well-formed XML, valid against the official Core XML Schema, and compliant with applicable specification constraints that schemas can’t express. That last clause is easy to miss. Schema validation catches structural problems, but it can’t replace checks for every semantic rule or project-specific invariant.

XLIFF 2.2 divides its specification into parts. Part 1 defines the minimum core elements and attributes needed for a valid XLIFF file; Part 2 covers the core plus optional modules for specific processes. The Part 1 specification says the 2.2 changes were designed to maintain compatibility with versions 2.0 and 2.1. That statement doesn’t guarantee compatibility with every individual CAT tool, extension, or workflow.

One notable 2.2 addition is the Plural, Gender, and Select Module. The module is intended to represent and process messages with variants, such as messages whose form depends on a count or grammatical selection. Teams working with variants should confirm that the extractor, CAT tool, and merger all support the module rather than assuming that support for XLIFF 2.2 Core includes every optional module.

The XLIFF 2.2 Core specification describes the design intent for compatibility with earlier 2.x versions.

The practical reading is narrower than “every old tool will work.” Version-level compatibility doesn’t prove that a particular tool understands every element, module, namespace, or extension in a file.

Before choosing a version, ask each tool provider for the specific capabilities relevant to your project. The OASIS FAQ recommends checking version support, file-size limits, translation-memory matches, binary units, custom namespaces and attributes, and complex languages. Add tests for your own extensions and roundtrip requirements.

A useful rule: pin a version and profile in the project specification, then test a representative file through every tool in the chain. Don’t let one team export “XLIFF” without recording whether that means 1.2, 2.1, or a particular 2.2 profile.

For teams deciding between XLIFF and other localization systems, SaaS localization workflows explains how resource extraction fits into continuous product development. A comparison of localization platforms can also help frame tool selection, while keeping file-format support separate from broader project-management features.

Notes, identifiers, placeholders, and unit boundaries¶

A translator can’t infer every interface condition from the source string. Context needs to travel with the unit, or the handoff becomes guesswork.

Write notes that answer a real question¶

A useful note explains something the source text doesn’t reveal. Include the string’s interface role, where it appears, what triggers it, and any constraints on translation. If a variable appears, explain what value it represents at runtime. If part of a string must remain unchanged, say which part and why.

Microsoft recommends XLIFF notes for useful context such as runtime placeholder values and UI usage. Its resource-exchange guide gives examples of comments from RESX resources mapped into XLIFF note elements. Mozilla’s localization guidance also recommends notes when strings contain variables, ambiguity, specialized context, non-localizable portions, or UI details unavailable to localizers.

Microsoft’s resource-exchange guide says:

“The comment can explain the conditions under which the string is displayed.”

The comment matters because the same string can require different translations depending on the condition or interface role. A note that says “shown after payment succeeds” is more useful than “text for UI.” A variable note should describe the runtime value, not merely repeat the variable name.

For example, a message such as "{count} items remaining" needs more than a literal gloss. The localizer needs to know whether count represents a number of files, tasks, or products and how the application handles plural forms. A note that identifies the noun and the display condition helps a translator choose the right construction. When the project uses a plural or select module, verify that the module is actually supported across the whole pipeline.

Give strings stable, descriptive identities¶

A string ID should communicate the message’s purpose, not just its position in a file. Names such as button_17 or label_2 carry little meaning outside the source code. A descriptive name gives reviewers and translators a clue even if the surrounding screen is unavailable.

Mozilla’s localization developer guidance states:

“The ID chosen for your string, regardless of the file format, should always be descriptive of the message and its role in the interface (button label, title, etc.).”

Treat an ID as an identity for a specific message in a specific context. Don’t reuse the same ID for two strings that happen to share their English text. The wording may diverge by language, or the strings may change independently in a later release. Separate IDs make the resource relationship explicit and reduce accidental coupling.

If the product changes a string’s meaning, update the context or ID according to the project’s rules. A stale ID with misleading notes can be worse than no note: it gives a translator false confidence. Version control and code review should cover resource identifiers and comments as part of the product change.

Protect placeholders and inline codes¶

Placeholders represent values or code that the translator shouldn’t translate as ordinary prose. Inline codes can also mark formatting or other structural content. A CAT tool may display these elements in a readable way, but the exported file must retain them in a form the merger understands.

A validator should check that required placeholders haven’t vanished, been duplicated, or been changed. Position can matter too: languages may require a different word order, so a placeholder might move while still remaining valid. Don’t write a simplistic rule that forces every placeholder to stay in its original character position. Define what the application can safely accept and test that rule against the target languages in scope.

The same care applies to markup. If the source contains a code around emphasized text or a link label, translators need to know whether the code is movable and which text it encloses. An export that converts protected markup into plain text can silently damage the result even when the target sentence reads well.

Teams translating structured documents face related risks when content is extracted from its original layout. The guide to preserving tables in translated DOCX files covers the layout side of that problem. XLIFF addresses structured exchange, but the native-format parser and final preview still determine whether document structure survives.

A practical XLIFF validation checklist¶

Validation should happen at more than one layer. XML syntax is only the first gate; a file can be valid XML and still be unusable in your localization pipeline.

1. Check XML well-formedness¶

Parse the file with an XML parser before running localization-specific checks. This catches malformed markup, broken entities, and structural syntax errors. A parser error usually points to a specific location, which makes it easier to identify whether the fault came from extraction, manual editing, or export.

Don’t treat a successful parse as proof of XLIFF conformance. Well-formed XML only proves that the document follows basic XML syntax.

2. Validate against the schema for the declared version¶

Use the official schema that matches the document’s XLIFF version. For XLIFF 1.2, select the appropriate Transitional or Strict schema; the specification says users must select the schema that fits the document. For XLIFF 2.1, validate against the official Core XML Schema. A 2.2 document should be checked with the relevant schemas and rules for the parts and modules it uses.

Record the chosen version and schema in the pipeline configuration. A generic “XLIFF validation” step that silently picks a schema can produce misleading results if the file declares a different version or namespace.

3. Run checks for rules the schema can’t express¶

Schemas can’t express every constraint in a specification. XLIFF 2.1 conformance includes applicable specification constraints beyond XML schema validity, so add a semantic validation layer. That layer can check relationships between source and target, required IDs, permitted state changes, project-specific metadata, and whether the selected module is allowed.

The validation rules should be explicit and reviewable. If a build rejects a file, show the unit ID and the failed rule rather than returning only “invalid XLIFF.” A useful error points an engineer to a repair; a vague error sends the file back and forth between teams.

4. Compare source and target content¶

Check that every expected source unit exists and that target content follows the workflow rules. The right rule for an empty target depends on the project: some workflows allow untranslated content to pass through, while others require targets before a release. Make that choice explicit rather than letting each tool interpret an empty target differently.

Compare protected values and inline codes. Validate placeholders by name or structure, not by raw string position. Check that non-translatable content hasn’t been added to the target and that any required terminology or language metadata remains present.

5. Check notes and extensions survive the pipeline¶

Import a test file into each CAT tool, export it, and compare its notes, custom attributes, and extension elements with the input. XLIFF can be extended, but processors aren’t required to understand non-XLIFF extensions. Preservation behavior depends on the tool and the conditions in the relevant specification.

A roundtrip test should include the extensions the real project uses, not just a minimal sample. If the tool drops an extension, decide whether to remove the dependency, change the workflow, or use a tool that preserves the required data.

6. Merge and inspect the native output¶

A valid XLIFF file isn’t the deliverable if the application or document is what users see. Merge target content back into the source format, then inspect the result in its actual layout. Microsoft recommends previewing localized output and testing text length, fonts, directionality, pagination, and wrapping in the original context. See Microsoft’s resource-exchange guide.

Run the application’s own tests as well. Verify that placeholders render, links work, controls remain usable, and text isn’t clipped. For documents, check page breaks, tables, and text flow. The review should include the output that ships, not just the XLIFF that passed a validator.

Checklist to keep beside your pipeline¶

• Confirm the XLIFF version and namespace.
• Use the matching version-specific schema.
• Run semantic and project-specific checks beyond schema validation.
• Check source and target coverage, IDs, placeholders, and inline codes.
• Confirm notes, custom attributes, and extensions survive import and export.
• Merge a representative file back into its native format.
• Preview the actual localized output and test it in context.

A useful test fixture includes ordinary text, a repeated word with different contexts, a placeholder, inline markup, an empty target, a note, and any custom extension used in production. Keep that fixture small enough to inspect by hand and rich enough to expose the failures your real content can trigger.

For automated systems, make validation repeatable in continuous integration. Store the version, schema, parser settings, and project rules alongside the pipeline configuration. When a tool upgrade changes how it reads or writes XLIFF, run the same fixture through the updated chain before accepting the change.

When XLIFF helps, and when another format may fit better¶

XLIFF is useful when content needs to pass between different localization tools or teams without tying the exchange to one vendor’s proprietary format. The OASIS FAQ describes the format as tool-neutral and extensible. A team can use that interchange role to separate extraction, translation, review, and merge responsibilities.

XLIFF fits especially well when:

• A product has a repeatable extraction and merge process.
• Multiple tools or organizations need to exchange localized content.
• The project needs source-target pairing, notes, or structured metadata.
• Engineers can test the exact format version and extensions in the tool chain.
• Translation and software release stages need a clear file handoff.

XLIFF may add needless work when a project has no meaningful exchange step and a simpler native format already supports the required workflow. The format doesn’t create context, correct bad segmentation, or guarantee that a target language is implemented properly. A small team should compare the cost of extraction, validation, and merging with the benefit of the interchange contract.

The specification’s focus on lossless interchange also suggests a practical boundary: don’t assume XLIFF is automatically the best internal representation for every processing task. The XLIFF 2.2 specification neither encourages nor prohibits that use. Decide based on the needs of the pipeline and test whether the format preserves what each stage needs.

For continuous software work, the file format is one layer of a larger system. A team also needs stable resource IDs, context, review rules, and a safe release path. SaaS localization workflows explores those operational pieces. Teams planning machine-assisted translation can also read about training custom MT on translation memories, while keeping XLIFF interchange and model training as distinct concerns.

FAQ¶

What is an XLIFF file and how does it work in localization?¶

An XLIFF file is an XML-based interchange file for localizable content. It carries structured source and target text, along with information such as identifiers, notes, and inline codes, between localization stages and tools.

What is the difference between XLIFF 1.2, 2.1, and 2.2?¶

XLIFF 1.2 uses its own namespace and offers Transitional and Strict schema variants. XLIFF 2.1 uses a later core specification, while XLIFF 2.2 adds a Plural, Gender, and Select Module and was designed to maintain compatibility with 2.0 and 2.1. That design doesn’t guarantee support for every tool or extension.

How do localization engineers validate an XLIFF file?¶

First parse the XML, then validate it against the schema for the declared version. Add checks for specification constraints that schemas can’t express, project rules, target coverage, placeholders, inline codes, notes, and extensions. Finish by merging the file and inspecting the localized output.

How does XLIFF extraction and merging work?¶

A parser reads the native source format and extracts translatable content into XLIFF. Translators work on target segments, while the pipeline preserves source structure in a skeleton or related data. A merger then puts the targets back into the native format, where the result needs a layout and functional review.

What should developers include in XLIFF notes and context?¶

Explain the message’s role, where and when it appears, what variables mean at runtime, and which parts must stay unchanged. Use descriptive, unique IDs and don’t reuse one ID for strings with different contexts.

How can I check whether a CAT tool supports my XLIFF version and extensions?¶

Ask the provider about the exact XLIFF version and modules, custom namespaces and attributes, file-size limits, binary units, translation-memory handling, and complex languages. Test a representative file through import and export, then compare the resulting extensions and metadata with the original.