How to ensure the correct structure of an XML source file

Owned by Damian Rozmiarkowski (Unlicensed)
Last updated: Jul 12, 2024 by Damian Rozmiarkowski
4 min read

Introduction

An incorrectly structured XML source file is the root cause for unsuccessful project analysis or many other problems with the content that is displayed for translation in XTM Workbench.

Below are the most prominent things that you should bear in mind while dealing with XML format as source files.

To modify your XML file to suit your requirements, we highly recommend that you open it in Notepad++ or another editor that supports XML syntax coloring.

Guidelines

  • The XML file should start with the XML declaration

Make sure, that your XML file starts with a proper XML declaration, i.e. <?xml version="1.0" encoding="UTF-8"?>.

See the example source file:

  • The XML file must only contain one root element

Remember, that your XML file must consist of one root element that wraps up all other elements.

  • Keep proper construction of the tags

Always keep in mind what the construction of a start tag <tag> and an end tag</tag> should look like. You can also use a self-closing tag, which looks like this: <tag />.

  • There must not be any entry before or after the root element

You should avoid using syntax like this (the root elements are marked green):

If any content is detected before or after the root element, as shown above, one of the following error messages will be displayed in the XTM Cloud UI, once the file has been analyzed:

  • Content is not allowed in prolog.

  • The markup in the document following the root element must be well-formed.

  • Unsupported characters

There are some characters that are not supported by the XML standard. To enter them correctly, you have to use a special syntax (also called as entity reference) instead of the actual character. The table below shows a few popular examples:

 

CHARACTER

HOW TO INSERT IT

(a special syntax that is to be entered in place of the actual character)

 

CHARACTER

HOW TO INSERT IT

(a special syntax that is to be entered in place of the actual character)

The character between tags (<tag>here</tag>)

&

&amp;

<

&lt;

>

&gt;

The character in an element value (<tag attribute="here" />)

''

&quot;

'

&apos;

  • An attribute value must be in quotes or apostrophes

Remember that an attribute value must always be in quotes or apostrophes, even if it is a number, i. e. <tag number="1" />.

  • Make sure that your file is compatible with the XML standard

The easiest way to do this is to open your file with a browser such as Google Chrome or Mozilla Firefox. If there are some mistakes, for example, your end tag looks like this <tag/> instead of </tag>, this kind of error message should be displayed (the example below comes from Mozilla Firefox):

After you fix the element specified in the error message above, the file looks like this:

A “File with no content” problem

This situation might occur if you want to translate the values of the attributes in your file rather than content between a start and end tag, which in this case is not present. In such a case, the following message will pop up in the XTM Cloud workflow after the file in question has been analyzed:

Changing the ITS configuration should solve such an issue. To perform a change of this kind, create a suitable ticket for the XTM International Support team and provide the following details:

  • Company login name,

  • URL you use to log into XTM Cloud,

  • Example project name or its ID, with a sample file. A description of the attributes or elements that should be included in or excluded from translation.

Good to know!

It is possible to configure file filter rules for XML files in the Filter templates. See How to create a filter template in the XTM UI and apply it to a project, for more details.