Translation of the Built-in Help
Understanding the format of the help
Basics about the Built-in Help Format
The format of the help is derived from XML and specified in the Understanding and Authoring OpenOffice 2.0 Online Help (pdf) document. Translators need not know all details, but should have a basic understanding of some terms.
Some content here is taken from Localizing Documentation (pdf) and adapted. The book itself refers to another translation tool, which was used for OpenOffice.org 2 and cannot be used directly.
- An XML element is a logical xml fragment that is surrounded by tags, e.g.
<paragraph role="heading">Paragraph Content</paragraph>
- A tag is the delimiter of an element and is enclosed in brackets:
<>. Most elements have an opening tag at the beginning and a closing tag at the end. The opening tag may contain attributes, for example
<paragraph role="heading">in the example above. The closing tag always starts with a slash
/and does not contain attributes, for example
</paragraph>in the example above. Some tags don't have any content, for example
<br></br>. These are sometimes also written as one standalone tag, for example
- An attribute might appear in the opening or standalone tag of an element and is used to further specify the element, e.g.
rolein the example above. An attribute always is associated with a value, e.g.
"heading"in the example above.
- Child element
- Element content can contain other (nested) elements. Such is called child element. You must copy the opening and closing tag of the child element exactly and translate the content of the child element.
You must not translate anything inside a tag but only the element content. The only exception is the value of the name attribute of a link element.
Example String 12958811
Choose <emph>Tools - Word Count</emph>.
In the source text in Pootle you see
<emph> is the opening tag,
</emph> is the closing tag. Do not translate them. You have only to translate the parts Choose and Tools - Word Count.
Notice, that Pootle uses different colors for the tags and for the actual text.
The tag pair
<emph> … </emph> causes, that the content is emphasized. This is done by showing the content in bold.
In the help you see Choose Tools - Word Count.
Sometimes Pootle shows you only the content, but in other cases you see the tags as well.
Sometimes you see red wave-lines, see picture below. They belong to line breaks in the source file. Such line breaks do not influence how the help text is shown, but are used by the developers to make the source text easier to read. You can ignore these red wave-lines.
The line breaks you see in Pootle depend on the width of the browser window and are irrelevant too. Write your text in the input field without any explicit line break. Texts which have to go to different paragraphs are separate records in Pootle.
Strings Used in the Index of the Help
Look at the example string 12958808. The help file has the content
<bookmark xml-lang="en-US" branch="index" id="bm_id3149686"> <bookmark_value>words; counting in text</bookmark_value> <bookmark_value>number of words</bookmark_value> <bookmark_value>documents; number of words/characters</bookmark_value> <bookmark_value>text; number of words/characters</bookmark_value> <bookmark_value>characters; counting</bookmark_value> <bookmark_value>number of characters</bookmark_value> <bookmark_value>counting words</bookmark_value> <bookmark_value>word counts</bookmark_value> </bookmark>
You see in Pootle
The bookmark element in connection with the attribute branch="index" means, that this is content to be shown in the Index tab of the help. Each of the bookmark_value elements determines an item for the index. If their is a semicolon, the left part is the main item and the right part is a subitem. Items in the index are sorted automatically, so you need not care of alphabetical order.
What must not be Translated
<There are some examples in LibreOffice Wiki and on http://openoffice.apache.org/translate.html>
<show examples for each item>
<StarBasic source code>
<Location inside the help>
<Find an item by filename and paragraph ID., link to Pootle_User_Guide/Technical_Helpers#Transforming_the_Style_of_the_Built-in_Help >