Do not translate:

Anything inside tags (XML elements)

The first and most important principle is that you are never allowed to edit anything inside tags. All text in tags and tag attributes – i.e. anything between the < and > characters marking the beginning and end of a tag – is strictly off limits for translators and editors. Don't even think about editing anything inside tags, this information doesn't even exist for you. Just ignore it.

Nothing inside tags is ever seen by the user so nothing inside tags ever needs to be translated or edited. For example, even though many of the words inside the following tag (in blue) are in English you are not allowed to translate them because they are inside the tag:

<config-value name="title" translate="true">Help &amp; Manual XML Language Reference</config-value>

You are only allowed to translate the text shown in red, because it is plain text between tags (and because the tag has a translate="true" attribute, see below).

Text tagged as translate="false"

This should be fairly obvious: In Help & Manual text can be protected against changing and this applies the attribute translate="false" to the text tag. Any text tagged with this attribute should be left unchanged unless the author specifically provides other instructions.

Element attributes

Element attributes are also inside tags so that is already a very good reason not to translate them. However, this point is so important we would like to repeat it. Don't even think about translating or editing the attributes of any XML elements. Again, none of these attributes are ever seen by the user so they don't need to be translated. If you do translate them you will create syntax errors and make it impossible for Help & Manual to open the project correctly.

In the following example too, you can only translate or edit the text shown in red. Everything else is strictly off limits. All the texts shown in green are element attributes. Editing or translating them will make it impossible to re-import the XML files because of the strictness of XML syntax.

<para styleclass="Heading2"><text styleclass="Heading2">What you are </text><text styleclass="Heading2" style="text-decoration:underline;">not</text><text styleclass="Heading2"> allowed to translate or edit:</text></para>

Of course, sometimes you will have to use your own judgment a little. In the example above you will have to move around the underline tags around the word "not" because the structure of the sentence will probably be quite different in another language. This is generally OK provided you do it carefully and don't move these tags outside any other tags enclosing them. Just be careful and if you are not entirely sure what you are doing leave it alone or get help from someone with more experience.

Ultimately, you will save a lot of time and frustration if you use a proper translation tool that hides the tags from you so you don't need to worry about them at all.

Text data between tags with the translate="true" attribute

What you may translate is very clearly defined. Every element containing translatable data is identified with the translate="true" attribute in the opening tag. This means that you don't even need to look at any elements that don't have this tag. If a tag has the attribute translate="false" just ignore its content.

Here too, of course, you are only allowed to translate or edit the text data between the tags. You are still not permitted to touch anything inside the tags themselves, even in the tags with translate="true".

Element

Translatable

text

Text is always translatable if its translate attribute is set to "true". Do not translate if translate="false" is set.

link

The captions of hyperlinks (topic links, web links, file links, script/macro links) are translatable if their translate attribute is set to true.

caption

Image captions are translatable if their translate attribute is set to true.

keyword

Keywords are always translatable. They always have a translate attribute and the setting is always "true".

Note that this does not apply to a-keywords! A-keywords are never seen by the user and should never be translated because this can break help functionality!

html-code

The translate attribute of html-code elements is always set to "true". However, whether a translation is really required will depend on the nature of the code. If in doubt, ask!

config-value

Only some config-value elements are translatable. If they have a translate attribute and it is set to true they can be translated. If not they should be left alone.