Difference between revisions of "Pootle User Guide/Translation Built-in Help"

Revision as of 11:58, 9 September 2019

>]]

>]]

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.

Element

An XML element is a logical xml fragment that is surrounded by tags, e.g. <paragraph role="heading">Paragraph Content</paragraph>

Tag

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 <br />.

Attribute

An attribute might appear in the opening or standalone tag of an element and is used to further specify the element, e.g. role in 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 File: helpcontent2/source/text/swriter/guide.po, Location: words_count.xhp#par_id3149821.5.help.text, String 12958811

Choose <emph>Tools - Word Count</emph>.

<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.

Line Breaks and Whitespace

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 File:helpcontent2/source/text/swriter/guide.po, Locations: words_count.xhp#bm_id3149686.help.text, 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.

Embedded Content

The help format allows to embed content from one help file into another. When you read text in the help window, you will not notice this. Use the help manipulation described in the section Transforming the Style of the Built-in Help to make such embedding visible.

Embedding is done by the elements embed and embedvar, for example <embedvar href="text/shared/guide/paintbrush.xhp#formatpaintbrush"/>. Such elements refer to a paragraph, section or variable in another file by the filename and the id value of the referenced part, formatpaintbrush in the example. The id is shown in the manipulated help, so that you can search for it in Pootle by searching for id="an id" in the source text. For example search for id="formatpaintbrush" to find the origin of the above mentioned embedded text fragment.

Images

Images are included by an image element. Inside of it you see an alt child element. It specifies an alternative text for the image. At a first glance it is confusing. But look at the colors in the source text. In the example you see, that only the word Icon has to be translated.

The image element may have a caption child element, but that is currently not used.

Extended Tooltips

The text for the extended tips are stored in the built-in help and therefore their text is in the project Apache OpenOffice 4.x Help although the text is shown in the UI.

Extended tips are provided by an ahelp element. It has a hid attribute to specify the help identifier, which connects the text to the UI element.

If you have set the environment variable HELP_DEBUG=true, you see the extended tip itself in the upper part and the help identifier in the lower part of the tip.

If you know the help identifier of an UI element, you can search for the related text in Pootle. But in contrast to the project Apache OpenOffice 4.x you do not search in location but in source text.

Unfortunately, if the attribute is hid=".", the help identifier is given earlier in the help file, in a branch attribute of a bookmark element for example. And such bookmark element has no content to translate and therefore no entry in the Pootle database.

Example: Edit a chart and call the context menu. It has the item Data Ranges. The extended tooltip shows Opens the Data Ranges dialog where you can edit Data Range and Data Series. and the help identifier uno.DataRanges. Imagine the text has an error and you need to find the string in Pootle to correct it. Your search for DataRanges gets no result.

In such cases you should search for the extended tip itself. If you use not only a single word but a longer part of the tip, the number of search results will be small.

Sometimes the attribute visibility="hidden" is used. Translate the content nevertheless. The value "hidden" causes, that the text is only shown as extended tooltip and not in the help window.

Switches

Switches are used to show only one of several alternative strings in the help window. Which content is shown is determined at runtime based on a condition. The switch element chooses a paragraph or section, the switchinline element chooses a fragment inside a paragraph.

The type of condition is given by a select attribute. Possible values are:

sys

Operating system. Runtime conditions are WIN UNIX MAC

appl

Application. Runtime conditions are WRITER CALC DRAW IMPRESS MATH BASIC CHART

distrib, target, lang, ver

These conditions are currently not used.

The different contents are given in case or caseinline elements. They have a select attribute too. It has one of the possible runtime condition as value. The default or defaultinline element is used, when the current runtime condition does not fulfill any of the other case or caseinline elements.

In a usual help window you see only those texts, where the condition is fulfilled by your current runtime environment.

On a Windows or Linux system the user sees hold down Ctrl and, on a MAC system the user sees hold down Command and.

The user on a Windows system sees The scanner must support the TWAIN standard. The user on a Linux system sees The scanner must support the SANE standard. The user on a MAC system sees nothing.

Calling the help from Impress the user sees Rename Slide, calling it from Draw or another application but Impress the user sees Rename Page.

Being a translator you likely want to see each possible text in the help window. For that purpose you have to manipulate your installation as described in section Transforming the Style of the Built-in Help.

Links

The link element creates a hyperlink, similar to those known from webpages. The target URL is given in the href attribute. The content of the link element provides the visible text of the link.

According to the specification, a link element should have a name attribute to fulfill accessibility requirements. And in contrast to all other elements, the value of the name attribute has to be translated, although it is inside the opening tag.

Items

The item element is used to characterize a part of the text. It is mostly used to provide a unique formatting for a class of objects. The class itself is given in the type attribute. For translators the case type="literal" is relevant. It indicates, that the content should perhaps not be translated, for example because it is a book title or a Basic statement. In other cases it may be translated, for example for localized function names in Calc. So you have to examine the content carefully to decide whether a translation is needed.

Placeholders

The help contains some placeholders. You will see current placeholders %PRODUCTNAME and %PRODUCTVERSION, and the deprecated placeholders $[officename] and $[officeversion]. When the help is displayed at runtime, the Main Transformation Style Sheet main_transform.xsl replaces the placeholder with the information from the configuration file.

Do not translate placeholders, but transfer them unchanged. Do not use the product name directly but always a placeholder. Otherwise the help will be wrong for different branding.

What must not be Translated

ToDo

<There are some examples in LibreOffice Wiki and on http://openoffice.apache.org/translate.html>

<show examples for each item>

<tag>

<placeholder>

<StarBasic source code>

Finding items

ToDo

<Find an item by filename and paragraph ID., link to Pootle_User_Guide/Technical_Helpers#Transforming_the_Style_of_the_Built-in_Help >

Finding errors from GSIcheck in POOTLE

After translating you might have checked the translated strings with GSIcheck. Which could have given you a list of ERROR and/or WARNING to be corrected, before the files are merged into POOTLE. By slightly adjusting the filename and paragraph identifier from the errorreport from GSIcheck, you can search for the offensive string in POOTLE.

You may find that GSIcheck gives you a number of errors like the one below:

Error: Translation, Line 45107, UniqueID
helpcontent2/source\text\sdraw\guide\eyedropper.xhp/help/par_id3150202/30//:
Expected Symbol: Close tag for \<emph\> at Position 35  ""

You can find these in POOTLE by using the search on Location

The location consist of the name of the file and the paragraph-ID (par_id)
There is a catch though.

helpcontent2/source\text\sdraw\guide\eyedropper.xhp/help/par_id3150202/30//

eyedropper.xhp#par_id3150202.30

By partly adjusting the string, delivered by GSIcheck, you can search in POOTLE on Location

So, replace /help/ from the string of GSIcheck to # and a possible / (slash) in the par_id between digits by a .' (dot)

Also, be sure to include the last part of the name of the file to avoid possible double par_ids

From the above example this will give you:

eyedropper.xhp#par_id3150202.30

which is a valid search for Location in POOTLE and gives you:

(The last </emph> was indeed missing the / at first, but that is already corrected in the image)