XLIFF (which stands for XML Localization Interchange File Format) is the standardized file format used to ensure portability and interoperability between translation tools. If you’re using MadCap Lingo, you may have seen this file format, as Lingo generates and uses XLIFF (.xlf) files internally for all projects. MadCap Lingo translation file bundles can either be a subproject that includes these files among other project files, or exclusively XLIFF files. Since other translation tools support XLIFF files, you can readily use these bundles when working with a translator or Language Service Provider (LSP) that doesn't have MadCap Lingo and is unfamiliar with the project files.

As the name indicates, XLIFF files appear as an XML structured document, which can be opened in any XML or text editor. This can be a big benefit in interpreting the behavior of MadCap Lingo or other tools that interact with the XLIFF file for translation.

Unfortunately, not all tools use XLIFF files in the same way, and some issues can occur when merging the translated files back into your MadCap Lingo project. When things go wrong, being familiar with some of the markup will be crucial in identifying and solving the issue.

How to Troubleshoot Three Common XLIFF Issues

Here are a couple of places where corruption often occurs and how to solve them:

Version Differences

XLIFF has different versions (1.0, 1.1, 1.2, 2.0, 2.1), with version 1.2 as the version used internally by MadCap Lingo. A corrupted document can occur if the version changes without the format of the document changing. In addition, if the version is changed by another tool and then returned in a translation bundle, it will be incompatible and will not merge back into your original project.

Editing the file and changing the version back to the original (in the case of MadCap Lingo and version 1.2) would be the easy fix. However, if the format of the file has been changed, you will most likely need to revert to the original file and translate using the translation memory to recreate any translation work.

Target Language

Before XLIFF Version 2.0, the source and target language were specified at the file level. If these are changed when changing tools, the file will result in either errors or the inability to merge a document back in.

In most cases, these changes occur because of minor language codes differences from tool to tool (for example, es changed to x-es-xl). In that case, change the target language directly in the file and import. Otherwise, you may need to clarify with your translator to ensure that you don’t accidentally associate sentences of one language with the wrong language code in your project and translation memory.

Wrong Markup Usage

Segment mark-up is by far the most easily corrupted part of the file. The trans-unit element generated by MadCap Lingo contains three elements: source, seg-source, and target.

The source element contains only original text and xliff tag markers (e.g. ph, bpt, ept).

The seg-source element is the segmented version of the source text in the unit. This means mrk elements identify individual sentences/segments. In MadCap Lingo 10, mrk tags are also used to preserve whitespace.

The target element is the translation of the seg-source. The same number and mrk tags in seg-source should exist in the target element and all the ids of the mrk should be present as well. Any xliff tag marker that exists in the seg-source mrk element should exist in the mrk tag with the same id.

In addition, any missing or misformatted mrk tags (either designating segments or preserving whitespace), missing or mismatching xliff tag markers, or missing segment elements (missing seg-source) will cause corruption.

Many other attributes and elements can exist in an XLIFF file. The full specifications for XLIFF 1.2 is available here. Any attributes in the XLIFF generated by MadCap Lingo that have the MadCap namespace (e.g. MadCap:segmentStatus) are specific to MadCap Lingo and will not be updated by other tools, but they will not cause corruption.

Identifying when corruption occurred is vital to understanding how to resolve the issue, so it's crucial maintain copies of the original XLIFF file generated from MadCap Lingo. You can either create a backup copy of your project or bind to source control to compare file changes. When escalating an issue to support or discussing the issue with MadTranslations or any other LSP, it's helpful to let them know what the workflow was (new project, project update, bundling, etc.) and what tools have been used.

Have any further questions or comments on how to use XLIFF files in the translation workflow? Feel free to leave a comment below, or reach out to the MadTranslations team for an in-depth look at your project.