Talk:Pootle User Guide

This page contains a draft of my plan for changing and update the content. Please edit here and discuss it on dev@openoffice.apache.org. Part like <comment> will be removed later.

---

The Apache Software Foundation runs a Pootle service to allow its projects an easy, cooperative way to localize their products. This guide describes how to use Pootle in the Apache OpenOffice project. As of August 2013, already 40 languages (out of the 120+ languages OpenOffice supports) are maintained in Pootle and more coming soon.

For an introduction to the localization process read http://openoffice.apache.org/translate.html and for a more general overview start at http://openoffice.apache.org/get-involved.html.

Registration and Login

You need not to register or login for helping in translation. Anyone can make suggestions in Pootle. Those will be reviewed by committers and then stored into the database.

Start with Pootle at https://translate.apache.org and choose your language and project in any order. The project Apache OpenOffice 4.x covers the strings, which can be seen in the user interface (UI), the project Apache OpenOffice 4.x Help covers the texts in the built-in help. Always choose the project with the highest version number.

<merged https://cwiki.apache.org/confluence/display/OOOUSERS/I%27m+a+new+Volunteer%2C+I+want+to+help! into this guide. Can it be removed on CWIKI?>

If you are seriously interested and will work collaboratively with the other translators, you can get a Pootle account.

1. Subscribe to the localization mailing list. Note: It's a public list and you will probably get many related mails, but it's a way to get in touch and communicate each other.
2. Introduce yourself on the list and find members in your language.
3. Become familiar with Pootle. If your language is missing on Pootle, ask on l10n@openoffice.apache.org to add it. We will react as soon as possible.
4. Ask for a Pootle account by sending an email:

 To: l10n@openoffice.apache.org
 Subject: New Pootle Account
 Body: 
 Hello my name is ..... and .... 
 Please create a Pootle account for me. I state that my contributions are under
 the Apache 2 license and I will work on ...<your language>...
 My preferred username is  ...<preferred username>...

The administrators of the Pootle server will contact you for username/password.

All project committers have automatically a Pootle accout and can use their Apache username/password on Pootle.

To login at Pootle click on the log-in text, top right in the blue area. Afterward you will find a link to your account settings in this area.

If you are willing to maintain the translation in the longer term, tell this on the mailing list and find collegues there. Add yourself to the list on https://cwiki.apache.org/confluence/display/OOOUSERS/Localization+Volunteers

Overview to the Pootle Online User Interface

Note: The user interface of Pootle is localized. Therefore the screenshots here show non English texts.

The user interface for committers has some additional items, but translating itself is the same as for anyone.

Tab page "Overview"

There are about roughly 100 pages texts to translate, most of them for the build-in help.

A The summary text in the upper left area provides predefined filters; it is the so called Quick Translate mode. It shows only items, which need to be worked on.

B The tree view follows the internal structure of the source code. Here you get access to all strings of a specific file; this is the so called Translate All mode. It shows all items, independent of their translation status. Hover the green bar to see what percentage of the folder is already translated.

C For correcting a single wrong text, you will likely need the search. Here on the overview tab page it is in the right top corner and on the translation tab page you find it in the left bottom corner. It will be explained in detail in section <insert local link>.

D For off-line translation<insert local link> you can download and upload .po-files. Find the links in the right part.

Choosing any of the modes A-C you get a list of translation records in the translation tab page. To switch back to the overview click on the left tab, top left on the screen.

Tab Page "Translate"

<Add screenshot with DEF... markers>

The tab page "Translation" shows a list of translation records. When you are logged in, you can set in your preferences, how many record lines are shown at a time. Click a record to open it, the other record will collapse automatically. Please be patient, Pootle reacts sometimes slowly.

The translation record line shows you

E

the file name of the .po file, which contains the string.
Such .po file collects basically the strings from one folder in the source code.

F

the exact position of the string in the source code.
Left of the # sign you see the file name, right of the # the identifier inside that file.

G

the terminology with translation suggestions of single words
<http://wiki.openoffice.org/wiki/Pootle_Glossary_Guide Is it relevant, is it correct?>

H

the English original text

I

In case you have selected alternative languages in the preferences of your account or the translation target language is different from your locale, you see here the translations into those languages too.

J

the input field to enter your translation

K

already existing translations of similar strings

L

a button to submit the suggestion.
When you hover the button with the mouse, you see a tooltip with a hint for a shortcut key.

Committers have in addition

M

a text link to toggle the button between Suggest and Submit

N

a link to open an input field for an comment

O

Buttons to accept or reject suggestions

In the lower part of the user interface you get

P

the search

Q

a direct link to the current translation record.
Such is useful, if you will reference a special translation item in an email, for example.

R

the navigation area.
Look at the tooltips to get further hints for navigation.

Offline translation

<I have no experience with offline translation. Need the existing text an update or is it sufficient to copy it?>

Quality Assurance (QA)

Peer review

<How to organize it?>

Show Pootle Warnings

<insert screenshot>

Click on the left tab to switch to the Overview. Click on the Detail link to show, what Pootle considers to be an error. You see a list with check categories and corresponding number of errors. At least the red, critical ones you have to examine carefully.

<insert screenshot>

Click on the proof item or on the number to get the list of translation records. Be patient even when your browser thinks that "a script has stopped working".

<insert screenshot>

The translation record shows too, that a check failed. And in the screenshot you can see, that Pootle is right in this example. Placeholders must not be translated.

<insert screenshot>

The list of failed records is available too from the "Translate" tabpage. Select the item "Check" from the "Filter"-drop-down-list at the bottom of the page. It is the last item in the list. Now you get a second drop-down-list to select the check category. The number in brackets tells you how many translation records failed the check.

Review language builds

Before the final release you will get a beta release in your language. Review it carefully to catch all translation errors.

If you want a localized version earlier, you have to build an own version. To get a localized build, use the configure switch --with-lang in your configure parameters.

Or you ask on the list; perhaps another member is able to provide you with a localized build or it is possible to set up a build bot accordingly.

Releasing a localized build

We have agreed to release a localized version of Apache OpenOffice, if the UI is 100% translated.

And for long-term maintainability we also recommend that:

• the UI is translated to 100% and

• the help is translated to 100% too and

• there is a small team (even just two members) to maintain the translation and ensure QA.

<How to verify the technical correctness of the translation? Add description here.>

When you are ready, write an issue in Bugzilla in the product <Native-Language>. Also write an issue, if you later on make changes to the translation and want them to be integrated into the next release.

Note that if you edit strings in Pootle you need to explicitly ask on the mailing list for them to be integrated into OpenOffice. Integration is not automatic.

How to Search

General

You will find, that it is a large problem in translation to be sure what part of the UI or the build-in help is shown in the current translation record and the other way round to find a specific string from the installed application in Pootle. The following sections shows you some tools.

<Remark: Write the description using concrete examples>

Search Inside Pootle

<Explain the check boxes and the filter>

Search in the Source Code

< Explain opengrok and viewvc>

Make Your Installation Verbose

Extended Tips

Set the environment variable HELP_DEBUG=true. It depends on your operating system how to do it. Find details on environment variables for Apache OpenOffice in http://wiki.openoffice.org/wiki/Environment_Variables

Now your extended tips in AOO look like this

Notice there is an additional part under the --- divider. The tip shows now the helpID of the item and the internal module. You can use the last part after the colon to search for it in Pootle, here search for CBX_PREVIEW for example.

Using extended tips is not enabled in the defaults. Use one of these ways to show extended tips

• Enable them in Tools > Options > OpenOffice > General
• In the toolbar "Standard" set the icon "What's this?" to visible. Click the icon and hover with the mouse over an UI element. Click again to leave this mode.
• Customize a toolbar and add the item "Extended Help" to it. Find it in the category "Application". This command has no icon assigned. To connect an icon to the command or change the command name to e.g. "Help+" click on the button "Modify" in the customization dialog and select the corresponding item. With this command you can easily toggle between extended tips on/off. Use a similar way to assign a shortcut key to this command.

Transforming the Style of the Build-in Help

Issue 56321 "Instructions on Help review" provides three tools to make the structure of the build-in help visible.

allfiles.tree

It adds an entry "All Help Documents for Debug Purpose" to the "Content" page of the build-in help. This new section shows the helpfiles not by title but by filename and in the same hierarchical order as in Pootle.

default.css

This file colors the help texts in a way, that you can easily see, what kind of content it is.

main_transform.xsl

This file causes, that in the build-in help the helpIDs are shown in addition to the text. With the information about file and location from Pootle, you can now easily identify the string in the help and see its context.

To transform your help do this:

1. Get the newest versions of the files allfiles.tree, default.css, and main_transform.xsl from Issue 56321 .
2. Close your OpenOffice including the Quickstarter.
3. Locate the folder "help" in your installation. For my Windows 7 it is the path C:\Program Files\OpenOffice 4\help. For you it should be similar.
4. You should see a file main_tranform.xsl in this folder. Rename it to e.g. main_transform.xsl.orig and copy the corresponding file form the issue here.
5. You should see subfolders that are named as the language codes. Open the folder of the language, for which you will produce the translation.
6. You should see some files with file extension .tree. Copy the file allfiles.tree here.
7. Locate the file default.css in this folder and rename it to e.g. default.css.orig. Copy the corresponding file from the issue here.
8. Start OpenOffice and open a help page. At top of the page you will see a short explanation about the meaning of the colors and styles.

<Some new files are missing in allfiles.tree. But I don't know yet, whether the file has to be updated manually or a script for generating the file exists.>

Using a KeyID -Build

<How to get a keyID build>

<How to use a keyID>

Tips and Tricks for Translation of the User Interface

Accelerator keys (mnemonic)

<see mail from Andrea>

How to find the string in my OpenOffice-Installation

<Problem description by example>

<get the application module>

<Search identifier in source to get other texts from the same dialog or menu.>

<Verify a candidate by the identifier>

How to find an UI string in Pootle

<Problem description by example>

<Case .uno:command, using it in the search>

<Using a keyID build>

Tips and Tricks for Translation of the Help

What must not be Translated

<show examples for each item>

<tag>

<placeholder>

<StarBasic source code>

Extended tips

<Location inside the help>

Finding items

<Find an item by filename and paragraph ID.>

General problems

The English word is ambiguous

<example: record -- database item or verb>

The corresponding UI Element does not exist

<example: main toolbar>

The English Help is Wrong

<writing issues>

I'm stuck

<native language mailing list>