Difference between revisions of "Talk:Pootle User Guide"

Revision as of 12:03, 12 August 2013

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. With August 2013 already 40 languages 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 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 build-in help. Always choose the project with the highest 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 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 consider to provide me with an account, I state that my contributions are under
 the Apache 2 license and I will work on ...<your language>...

The administration 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 colleges 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.

<Add screenshot with ABCD markers>

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

The summary text A 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.

The tree view B beneath 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.

For correcting a single wrong text, you will likely need the search C. It will be explained in section <insert local link>.

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

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

<Add screenshot with DEF... markers>

Click a record to open it, the other record will collapse automatically. Please be patient, Pootle reacts sometimes slowly. When you are logged in, you can set in your preferences, how many record lines are shown at a time.

A translation record consists of

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 you locale, you see here the translations of that 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 Commit

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 >

< Show Pootle details >

< 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 translated to 100% and

• the help is translated to at least <how much?>% and

• there are at least <two or three?> members to maintain the translation in a longer term.

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

When you are ready, write an issue in Bugzilla in the product <Internationalization or 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.

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

<Environment variable>

<extended tips>

<allfiles.tree and changed default.css>

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>