Difference between revisions of "Talk:Pootle User Guide"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Make your Installation Verbose: Extended Tips with screenshot)
m (Tab Page "Translate")
Line 123: Line 123:
Committers have in addition
Committers have in addition
;M: a text link to toggle the button between ''Suggest'' and ''Commit''
;M: a text link to toggle the button between ''Suggest'' and ''Submit''
;N: a link to open an input field for an comment
;N: a link to open an input field for an comment

Revision as of 19:43, 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 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
 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.

Tab page "Overview"

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

PootleGuideA QuickTranslateExample2.png
PootleGuideA QuickTranslateExample1.png

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.

PootleGuideB TreeView.png

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.

PootleGuide SearchField.png

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

PootleGuide DownloadUpload.png

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

PootleGuide TabPageOverview.png

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.

PootleGuide TabPageTranslationWithMarkers.png

The translation record line shows you

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.
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.
the terminology with translation suggestions of single words
<http://wiki.openoffice.org/wiki/Pootle_Glossary_Guide Is it relevant, is it correct?>
the English original text
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.
the input field to enter your translation
already existing translations of similar strings
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.
PootleGuide TranslateInCommiterViewWithMarkers.png

Committers have in addition

a text link to toggle the button between Suggest and Submit
a link to open an input field for an comment
Buttons to accept or reject suggestions

In the lower part of the user interface you get

the search
a direct link to the current translation record.
Such is useful, if you will reference a special translation item in an email, for example.
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 stop 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 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


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

PootleGuilde ExtendedTipExample.png

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 assign. You can connect an icon to the command or change the command name to e.g. "Help+" clicking on the button "Modify" in the customization dialog. With this command you can easily toggle between extended tips on/off. Use a similar way to assign a shortcut key to this command.

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



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

Personal tools