|
|
| (One intermediate revision by the same user not shown) |
| Line 1: |
Line 1: |
| − | 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 new Pootle User Guide is "live" now. But you will find a lot of "ToDo"s and empty sections. Please help to complete the guide and to correct all the errors. |
| − | -----
| + | |
| | | | |
| − | [http://www.apache.org/| The Apache Software Foundation] runs a Pootle Translate 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.
| + | At the beginning of each page you find a template, that shows the TOC from the right sight. It is the same on every page and should therefore be easy to translate. |
| | | | |
| − | 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.
| + | At the end of the page is a list of languages. These are shown automatically in the left column. The links itself are dummies, but will you help to find the form, when you translate the content. |
| | | | |
| − | == Registration and Login ==
| + | I hope you find the new Pootle User Guide useful. [[User:Regina|Regina]] ([[User talk:Regina|talk]]) 12:51, 22 August 2013 (UTC) |
| − | | + | ---- |
| − | 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.
| + | |
| − | | + | |
| − | # Subscribe to the [http://openoffice.apache.org/mailing-lists.html#localization-mailing-list-public| 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.
| + | |
| − | # Introduce yourself on the list and find members in your language.
| + | |
| − | # 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.
| + | |
| − | # 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<br /> 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. When you login, you can choose the language of the Pootle UI.
| + | |
| − | | + | |
| − | The user interface for committers has some additional items, but translating itself is the same as for anyone.
| + | |
| − | | + | |
| − | === Tab page "Overview" ===
| + | |
| − | [[File:PootleGuideA_QuickTranslateExample2.png|250px|thumb|right]]
| + | |
| − | ;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.
| + | |
| − | [[File:PootleGuideA_QuickTranslateExample1.png|250px|thumb|left]]
| + | |
| − | | + | |
| − | <br style="clear:both;" />
| + | |
| − | | + | |
| − | [[File:PootleGuideB_TreeView.png|250px|thumb]]
| + | |
| − | | + | |
| − | ;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, regardless of their translation status. Hover the green bar to see what percentage of the folder is already translated. There are about 440000 words in the built-in help and 90000 words in the UI to translate.
| + | |
| − |
| + | |
| − | <br style="clear:both;" />
| + | |
| − | | + | |
| − | [[File:PootleGuide_SearchField.png|thumb]]
| + | |
| − | | + | |
| − | ;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''>.
| + | |
| − | | + | |
| − | <br style="clear:both;" />
| + | |
| − | | + | |
| − | [[File:PootleGuide_DownloadUpload.png|250px|thumb]]
| + | |
| − | | + | |
| − | ;D: For [[#Off-line_Translation | off-line translation]] you can download and upload .po-files. Find the links in the right part.
| + | |
| − | | + | |
| − | <br style="clear:both;" />
| + | |
| − | | + | |
| − | [[File:PootleGuide_TabPageOverview.png|thumb]]
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | <br style="clear:both;" />
| + | |
| − | | + | |
| − | === Tab Page "Translate" ===
| + | |
| − | {{Documentation/Tip|Most UI elements have got a tooltip. Those have information about shortcut keys in addition. So hover with the mouse and explore the UI.}}
| + | |
| − | | + | |
| − | 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, after some seconds additional elements are shown. You might need to allow your browser to show "unsafe" sites.
| + | |
| − | | + | |
| − | [[File:PootleGuide_TabPageTranslationWithMarkers.png|600px|none]]
| + | |
| − | | + | |
| − | The area of the active translation record shows you
| + | |
| − | | + | |
| − | ;E: the '''file name''' of the .po file, which contains the string.<br /> Such .po file collects basically the strings from one folder in the source code.
| + | |
| − | | + | |
| − | ;F: the '''location''', the exact position of the string in the source code.<br /> Left of the # sign you see the file name, right of it the identifier of the string.
| + | |
| − | | + | |
| − | ;G: the '''Terminology''' with translation suggestions of single words.<br />Read details on [[Pootle_Glossary_Guide]]. Ask the administrators in case you want to use such '''Glossary''' for your language.
| + | |
| − | | + | |
| − | ;H: In case you have selected alternative languages as additional source text 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.
| + | |
| − | | + | |
| − | ;I: the original English text, the '''source''' text
| + | |
| − | | + | |
| − | ;J: the input field to enter your translation, the '''target''' text
| + | |
| − | | + | |
| − | ;K: a '''suggestion''' from another translator<br />Hover the picture or avatar to see the name, click it to show the account information.
| + | |
| − | | + | |
| − | ;L: already existing translations of similar strings<br />Read details on [[Pootle_Glossary_Guide]]. Ask the administrators in case you want to use such '''Translation Memory''' for your language.
| + | |
| − | | + | |
| − | ;M: a button to submit the suggestion.
| + | |
| − | | + | |
| − | ;R: This is a link to the mobile version of Wikipedia. Mark a term on the screen and then click on icon <tt>W</tt> to see its entry in the Wikipedia.
| + | |
| − | | + | |
| − | In the footer, in the lower part of the user interface you get
| + | |
| − | | + | |
| − | ;N: the '''search''', see section [[#Search_and_Filter| Search and Filter]] for details
| + | |
| − | | + | |
| − | ;O: the '''filter''' to restrict the set of shown translation records to special kinds, suggestions or untranslated e.g.
| + | |
| − | | + | |
| − | ;P: a direct link to the current translation record.<br />Copy it, if you will reference this special translation record in an email, for example.
| + | |
| − | | + | |
| − | ;Q: the navigation area.<br />Look at the tooltips to get further hints for navigation.
| + | |
| − | | + | |
| − | If you do not see all elements in the footer, make your browser window wider.
| + | |
| − | | + | |
| − | If you are logged in, you have some items more.
| + | |
| − | | + | |
| − | [[File:PootleGuide_TranslateInCommiterViewWithMarkers.png|600px|thumb|none]]
| + | |
| − | | + | |
| − | ;S: a text link to toggle the button between ''Suggest'' and ''Submit''
| + | |
| − | | + | |
| − | ;T: a checkbox to mark, that the translation '''needs work'''.<br />This state was called ''Fuzzy'' in previous Pootle versions. You can use it as filter.
| + | |
| − | | + | |
| − | ;U: Buttons to accept or reject suggestions
| + | |
| − | | + | |
| − | ;V: a link to open an input field for a '''comment'''
| + | |
| − | | + | |
| − | === Search and Filter ===
| + | |
| − | | + | |
| − | ====Search Properties====
| + | |
| − | [[File:PootleGuide_SearchFields.png|192px|right]]
| + | |
| − | *The search is only executed on the current active set of files. Select the files in the ''Overview'' tab page and/or restrict the selection with the filter. To start with all files click the project name on the ''Overview'' tab page and then click on the tab ''Translate''.
| + | |
| − | *Only the fields ''Source Text'', ''Target Text'', ''Comments'', and ''Locations'' are searchable. Combine them as you like. When you click into the search field a popup with check-boxes opens; you have to check at least one. The settings are remembered for your next search.
| + | |
| − | *The short cut key Strg+Shift+S put the cursor into the search field without opening the popup.
| + | |
| − | *Press enter key or click the magnifier icon to start search.
| + | |
| − | *The search is not case sensitive, e.g. ''Page'' will find ''page'' too.
| + | |
| − | *The search is not restricted to whole words, but will find part of words too, e.g. "lign" will find "alignment".
| + | |
| − | *There exists no explicit AND or OR or NOT. Two words which are separated by a blank, are treated as two terms and connected with AND.
| + | |
| − | *Searching for exact phrases is not possible. e.g. ''line spacing'' cannot be searched as single phrase, but will be treated as search for ''line AND spacing''.
| + | |
| − | *The search uses UTF-8 coding, so non-Latin scripts can use it too.
| + | |
| − | *The search term may have special characters like dot, colon, or tilde.
| + | |
| − | *You cannot restrict the search to previous search results. Each search starts newly.
| + | |
| − | *The search term must not start with a blank, otherwise you get no results at all.
| + | |
| − | | + | |
| − | ====Using subset of files====
| + | |
| − | To work on the whole set of files go to the ''Overview'' tab page, click on the project and then on the tab ''Translate''.
| + | |
| − | | + | |
| − | To work on a subset of files you can restrict your work to a subfolder or apply a filter. You can combine this two methods, first select the subfolder and then the filter.
| + | |
| − | | + | |
| − | '''Subfolder'''
| + | |
| − | | + | |
| − | To work on a '''subfolder''' go to the Overview tab page and
| + | |
| − | * click on the number in the column ''total'' for the desired subfolder or
| + | |
| − | * doubleclick the subfolder you are interested in, so that you see its content, and then click on the tab 'Translate''.
| + | |
| − | | + | |
| − | '''Filter on Overview Page'''
| + | |
| − | | + | |
| − | To apply a filter starting on the Overview tab page
| + | |
| − | * click on the text "Continue translation" or "Review suggestions".
| + | |
| − | * click on a number in the column "Need translation" or "Suggestion".
| + | |
| − | * click on the text "Expand details" and then click on one of the criteria texts links or an number link.
| + | |
| − | When you hover a link with the mouse you can see in the status bar of your browser, which filter it applies.
| + | |
| − | | + | |
| − | '''Filter on Translate Page'''
| + | |
| − | | + | |
| − | To apply a filter starting on the Translate tab page, open the Filter drop-down list and click on the filter name. In case of the filter "Checks" you get a second drop-down list to select the criterium.
| + | |
| − | *<tt>All</tt> shows all records. If you have selected a subfolder, it does not show all records of the database, but only those of the subfolder.
| + | |
| − | *<tt>Translated</tt> shows all already translated records, useful for fixing errors in submitted strings.
| + | |
| − | *<tt>Incomplete</tt> shows untranslated records and records with "Need work" checked.
| + | |
| − | *<tt>Untranslated</tt> shows only untranslated records.
| + | |
| − | *<tt>Needs work</tt> shows only records with "Need work" checked. This state is called "fuzzy".
| + | |
| − | *<tt>Suggenstions</tt> shows suggestions, useful for review.
| + | |
| − | *<tt>My Suggenstions</tt> shows suggestions by the current translator. Translaters not logged in are tracked as ''nobody''.
| + | |
| − | *<tt>My submissions</tt> shows submission by the current translator, only useful if you are logged in.
| + | |
| − | *<tt>My overwritten submissions</tt> shows changes on your submissions. There should have been a discussion in your team about those records or at least a comment should have been added.
| + | |
| − | *<tt>Check</tt> shows only records where Pootle has found a problem, see section [[#Show_Pootle_Warnings| Show Pootle Warnings ]] for details.
| + | |
| − | | + | |
| − | == Off-line Translation ==
| + | |
| − | | + | |
| − | {{Documentation/Caution| Before starting to translate off-line, you should make sure to coordinate the translation activity with your team.}}
| + | |
| − | | + | |
| − | <'' Need the existing text an update or is it sufficient to copy it? --- the text in translate.html is accurate''>
| + | |
| − | | + | |
| − | If you want to translate off-line, you need to download the files from Pootle and to upload them once translated. These options are available on the "Overview" tab page.
| + | |
| − | | + | |
| − | === Download Files ===
| + | |
| − | | + | |
| − | [[File:PootleGuide_PrepairForDownload.png|300px|thumb|none]]
| + | |
| − | | + | |
| − | You can download either the complete project files, or by folder, or single files. First select the folder in the tree-view on the left side of the "Overview" tab page, so that you see the content of the folder. Then click "Download". You need to wait a little bit, because the .zip file is generated on demand. In the situation shown in the picture you would get a file <tt>aoo40help-de-helpcontent2-source-text-sdraw.zip</tt>. Notice that the file name contains the path as it is shown on the picture.
| + | |
| − | | + | |
| − | === Work Off-line ===
| + | |
| − | You can work with a preferred editor. Most commonly used editors by community are:
| + | |
| − | | + | |
| − | * [http://www.poedit.net Poedit]
| + | |
| − | | + | |
| − | * [http://www.omegat.org OmegaT]
| + | |
| − | | + | |
| − | If you want to work with only fuzzy/untranslated strings, an extra step is needed to filter those strings from downloaded .po file.
| + | |
| − | | + | |
| − | * Run [http://translate.sourceforge.net/wiki/toolkit/pofilter pofilter] which is a part of Translate Toolkit. You can download Translate Toolkit from [http://sourceforge.net/project/showfiles.php?group_id=91920&package_id=97082 here]
| + | |
| − | ** ''pofilter -t isfuzzy -t untranslated <input file> <filtered file>''
| + | |
| − | | + | |
| − | This will extract all strings which are fuzzy or untranslated.<br />
| + | |
| − | | + | |
| − | Once you finish working in filtered po file, you can merge it back into the original file using [http://translate.sourceforge.net/wiki/toolkit/pomerge pomerge] before uploading to Pootle.
| + | |
| − | | + | |
| − | === Upload Translated Files ===
| + | |
| − | Once translation is completed, you need to upload your work to Pootle.
| + | |
| − | | + | |
| − | There are three options of upload. Anyone has the option "suggest", logged in users have the additional options "merge" and "overwrite".
| + | |
| − | {|
| + | |
| − | |-
| + | |
| − | | [[File:PootleGuide_Upload_Anyone.png|250px|thumb]]
| + | |
| − | | [[File:PootleGuide_Upload_Commiter.png|250px|thumb]]
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | ;suggest: All changes are treated as suggestions.
| + | |
| − | | + | |
| − | ;merge: Default option for logged in users. Previously untranslated strings are submitted and the modifications of already translated strings are marked as 'suggestion', which means they need a review before submission. If you make some modifications to existing translations (e.g., bug fixing), please make sure that they are reviewed and accepted by reviewer. Unless, the modifications won't be applied.
| + | |
| − | | + | |
| − | ;overwrite: The uploaded file overwrites the existing file on Pootle. This option should be carefully used as it has possibility to loose existing data. If you make sure all the contents of your file are valid, you can choose 'overwrite' option for quick upload.
| + | |
| − | | + | |
| − | Note: During uploading, you should make sure that you're located in the right folder. You should upload a .zip file in the same folder that you downloaded it from. If you upload a file to a wrong location, please contact aPootle administrator.
| + | |
| − | | + | |
| − | == Quality Assurance (QA) ==
| + | |
| − | ===Peer review===
| + | |
| − | | + | |
| − | <''How to organize it?''>
| + | |
| − | | + | |
| − | ==== Review Suggestions ====
| + | |
| − | If you have got a Pootle account, you'll be able to accept or reject suggestions from other translators.
| + | |
| − | * Select a project and your language.
| + | |
| − | * To restrict the shown translations records to those with suggestions do one of these:
| + | |
| − | ** Click on "Review suggestions" in the "Overview" tab page.
| + | |
| − | ** Click on the number in the column "Suggestions" on the tree view in the "Overview" tab page
| + | |
| − | ** Choose the filter "Suggestions" in the "Translate" tab page.
| + | |
| − | : If you first choose a folder and then set a filter, the shown translation records are restricted to this folder.
| + | |
| − | * Go through the suggestions one by one. Accept or reject the suggestion. If the suggestion is accepted, it is submitted. If it is rejected, the existing translation will not be changed. Click on "Next string" without action to skip a suggestion.
| + | |
| − | | + | |
| − | ==== Checkbox "Needs work" ====
| + | |
| − | Some teams want to have all new or modified translations reviewed. To make it different from suggestions from anonymous translators without account, they can agree to use the "Needs work" checkbox. In previous versions of Pootle this checkbox was labeled "fuzzy". So you find instructions to organize review by marking changes as "fuzzy" and let the reviewer "unfuzzy" it after verifying that the translation is correct. To filter for these changes use the filter item "Needs Work".
| + | |
| − | | + | |
| − | <''Any other good tips?''>
| + | |
| − | | + | |
| − | ===Show Pootle Warnings===
| + | |
| − | [[File:PootleGuide_OverviewDetails.png|250px|thumb|left]] | + | |
| − | | + | |
| − | Click on the left tab to switch to the Overview. Click on the ''Detail'' link to show, what Pootle considers to be an error.
| + | |
| − | <br style="clear:both;" />
| + | |
| − | | + | |
| − | [[File:PootleGuide_OverviewShowDetails.png|250px|thumb|left]]
| + | |
| − | | + | |
| − | You see a list with check categories and corresponding number of errors. Find a description of the categories [http://docs.translatehouse.org/projects/translate-toolkit/en/latest/commands/pofilter_tests.html| here]. Please examine especially <code>XML tags</code> -warnings very carefully.
| + | |
| − | | + | |
| − | Click on the category or on the number to get the list of translation records. Be patient; click on "continue", when your browser thinks that "a script has stopped working".
| + | |
| − | <br style="clear:both;" />
| + | |
| − | | + | |
| − | [[File:PootleGuide_PlaceholderCheckFail.png|250px|thumb|left]]
| + | |
| − | | + | |
| − | The translation record shows too, that a check failed.
| + | |
| − | <br style="clear:both;" />
| + | |
| − | | + | |
| − | [[File:PootleGuide_PlaceholderCheckExamineText.png|350px|thumb|left]]
| + | |
| − | And in the screenshot you can see, that Pootle is right in this example.
| + | |
| − | | + | |
| − | In case of a false positive warning, e.g. "Repeated word" warning for the English string "Dot Dot Dash" (which is a line style), you can click on the "No entry"-sign to remove this warning from the record.
| + | |
| − | <br style="clear:both;" />
| + | |
| − | | + | |
| − | [[File:PootleGuide_FilterTypCheck.png|450px|thumb|none]]
| + | |
| − | | + | |
| − | The list of failed records is available too from the "Translate" tab page. Select the item "Checks" from the "Filter by"-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===
| + | |
| − | | + | |
| − | A few weeks before the final release you will get a beta release in your language. Watch the localization mailing list for announcements. Encourage your local community to review the build carefully to catch all translation errors.
| + | |
| − | | + | |
| − | You can build OpenOffice yourself or ask a community member to do it for you, to get a localized build. But prior to building the translated strings from Pootle have to be reintegrated into trunk. So ask for this on the localization mailing list, if you need an intermediate localized build.
| + | |
| − | | + | |
| − | == 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 [https://issues.apache.org/ooo/enter_bug.cgi| 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.
| + | |
| − | | + | |
| − | == Technical Helpers ==
| + | |
| − | | + | |
| − | You will find, that it is a large problem in translation to be sure what part of the UI or the built-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 show you some tools.
| + | |
| − | | + | |
| − | === Using an English User Interface Parallel ===
| + | |
| − | Because the user interface settings in Apache OpenOffice are bound to the user and not to the installation, you can generate a second user, who has an English interface. Then you can open Apache OpenOffice at the same time with an English user interface and with the UI in your language.
| + | |
| − | | + | |
| − | ==== Windows ====
| + | |
| − | * Download the English language pack and install it. Or the other way round, install an English version and a language pack for your language.
| + | |
| − | * Create a folder that will contain the user settings for the "English" user, for example "D:\AOOuser_English".
| + | |
| − | * Find the file soffice.exe in your installation and create a link to it on your desktop. That should be possible with right click and "Sent To".
| + | |
| − | * Open the link to edit it. It should has a field with the link target like "C:\Program Files\OpenOffice 4\program\soffice.exe".
| + | |
| − | * Klick into this field and move the cursor to outmost right position and add<br /> <tt>-env:UserInstallation=file:///d:/AOOuser_English.</tt><br />Notice that here a UNC notation with forward slashes is used.
| + | |
| − | * Close dialog with OK.
| + | |
| − | * Start OpenOffice with double-click on this link. Goto Tools > Options > Language Settings > Languages and set the User Interface to "English (USA)".
| + | |
| − | | + | |
| − | Dependent on the installation order it might be necessary to change your actual user settings back to your language.
| + | |
| − | | + | |
| − | ==== Other Operating Systems ====
| + | |
| − | ''For other operating systems this might be slightly different. Please add necessary descriptions here.''
| + | |
| − | | + | |
| − | | + | |
| − | === Search in the Source Code ===
| + | |
| − | Translators generally do not have a local copy of the code, but sometimes want to lookup something. This tools might help you:
| + | |
| − | ==== Opengrok ====
| + | |
| − | Example: You see the string "Purple Pipe" as name of a color gradient and wants to know, which files contain this string.
| + | |
| − | | + | |
| − | To search the code use http://opengrok.adfinis-sygroup.org/ That is as powerful tool for developers. For translators this short instruction might be sufficient:
| + | |
| − | * Select "aoo-trunk" on the right side.
| + | |
| − | * Enter the search term in the "Full Search" field. The wild cards * and ? are allowed, but not as first character. A phrase has to be enclosed with quotation marks. If you enter several words, they are automatically treated as been connected by AND.
| + | |
| − | * In the field "File Path" you can enter a part of the path or filename, for example 'helpcontent2' for all files of the built-in help. Or you use NOT to exclude those paths, you know to be irrelevant.
| + | |
| − | {|
| + | |
| − | |-
| + | |
| − | | [[File:PootleGuide_OpenGrok.png|400px|thumb|left]]
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | In the example you will find that the string "Purple Pipe" is contained in the file <tt>standard.sog</tt>. Click on the search result to open the file in your browser.<''See {{bug|122790}}, why this string is not yet (August 2013) in Pootle.''>
| + | |
| − | | + | |
| − | ==== viewvc ====
| + | |
| − | This tool provides a read access to all files of Apache-SVN. The tree of the OpenOffice project starts in http://svn.apache.org/viewvc/openoffice .
| + | |
| − | | + | |
| − | You will notice, that this is similar to the tree view in the page "Overview" in Pootle. Click on the directory name to open that folder and move down in the tree, click on "Parent directory" to move up.
| + | |
| − | | + | |
| − | A click on a file name gives you its revision log. To view the current file in the browser, click "View" of the top entry; use "Download" to save it to your PC. To go back, up in the tree, use the navigator line at top of the page.
| + | |
| − | {|
| + | |
| − | |-
| + | |
| − | | [[File:PootleGuide_viewvc_localizesdf.png|400px|thumb|left]]
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | | + | |
| − | The .po files for the user interface are based on <tt>localize.sdf</tt> files. Each language has its own file. Find these files in http://svn.apache.org/viewvc/openoffice/trunk/extras/l10n/source/. These files are about 13MB in size. <''As of August 2013, there are plans to get rid of the localize.sdf files and use .po files directly. Such change was already done in LibreOffice.''>
| + | |
| − | | + | |
| − | The .po files for the built-in help are based on .xhp files. Find these files in http://svn.apache.org/viewvc/openoffice/trunk/main/helpcontent2/source/text/
| + | |
| − | | + | |
| − | === 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
| + | |
| − | <div style="margin-left:3em">
| + | |
| − | '''Tip for Linux'''
| + | |
| − | | + | |
| − | Find the shell script <tt>soffice</tt> in your installation of AOO and open it in an editor. Add the lines
| + | |
| − | <source lang="bash">
| + | |
| − | HELP_DEBUG=true
| + | |
| − | export HELP_DEBUG
| + | |
| − | </source>
| + | |
| − | A good place to add them is after the already existing environment variable SAL_ENABLE_FILE_LOCKING.
| + | |
| − | </div>
| + | |
| − | | + | |
| − | Now your extended tips in AOO look like this
| + | |
| − | | + | |
| − | [[File:PootleGuilde_ExtendedTipExample.png|300px|thumb|none]]
| + | |
| − | | + | |
| − | 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 Built-in Help ====
| + | |
| − | {{bug|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:
| + | |
| − | # Get the newest versions of the files allfiles.tree, default.css, and main_transform.xsl from {{bug|56321}}.
| + | |
| − | # Close your OpenOffice including the Quickstarter.
| + | |
| − | # 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.
| + | |
| − | # You should see a file main_transform.xsl in this folder. Rename it to e.g. main_transform.xsl.orig and copy the corresponding file form the issue here.
| + | |
| − | # You should see subfolders that are named as the language codes. Open the folder of the language, for which you will produce the translation.
| + | |
| − | # You should see some files with file extension .tree. Copy the file allfiles.tree here.
| + | |
| − | # 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.
| + | |
| − | # 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; link to existing pages in this wiki''>
| + | |
| − | | + | |
| − | <''How to use a keyID''>
| + | |
| − | | + | |
| − | | + | |
| − | == Tips and Tricks for Translation of the User Interface ==
| + | |
| − | | + | |
| − | ===Accelerator keys (mnemonics) ===
| + | |
| − | | + | |
| − | <''see mail from Andrea; explain difference with shortcuts like CTRL-O''>
| + | |
| − | | + | |
| − | === How to find a 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''>
| + | |
| − | | + | |
| − | ===What File Name and Location Can Tell You===
| + | |
| − | You will see in the following examples, that the filename and location can tell you a lot. Imagine you need to work on the string "line spacing". A search will give you numerous results. Here are some of them, try to find the part in the UI ;)
| + | |
| − | | + | |
| − | '''1'''
| + | |
| − | | + | |
| − | [https://translate.apache.org/da/aoo40/translate.html#unit=12961852 Example unit=12961852]
| + | |
| − | | + | |
| − | File:<tt>cui/source/tabpages.po</tt>
| + | |
| − | | + | |
| − | The file name tells you from which source directory the strings are collected. Sadly the total overview of the directories at [[Source_code_directories]] is not updated to AOO4. <''A new version for AOO4 is needed.''>
| + | |
| − | | + | |
| − | <tt>cui</tt> derives from ''common user interface'' and contains parts that are used by several modules.
| + | |
| − | | + | |
| − | <tt>tabpages</tt> are pages in a dialog.
| + | |
| − | | + | |
| − | Location: <tt>paragrph.src#RID_SVXPAGE_STD_PARAGRAPH.FL_LINEDIST.fixedline.text</tt>
| + | |
| − | *<tt>paragrph.src</tt> The file, which contains the string. Most strings from the UI are defined in <tt>.src</tt> files. Looking into the source you will see, that this file contains the structure of the dialog. The name "paragrph" sounds like "paragraph", a strong indicator, that this "line spacing" belongs to text formatting.
| + | |
| − | *<tt>RID_SVXPAGE_STD_PARAGRAPH</tt> The string belongs to a dialog page about paragraphs. The letters RID are an acronym for ''resource identifier''.
| + | |
| − | *<tt>FL_LINEDIST</tt> <tt>FL</tt> might derive from ''fixed line'' and <tt>LINEDIST</tt> from ''line distance''.
| + | |
| − | | + | |
| − | *<tt>fixedline</tt> Now your are sure, it is a fixed line. The string is used to group the dialog page.
| + | |
| − | | + | |
| − | Find ''Show''|''Hide'' and ''More''|''Less'' links directly above and below the active translation record. In this light green area, you see strings, which are near to the current one in the source code. They likely belong to the same dialog page.
| + | |
| − | | + | |
| − | '''2'''
| + | |
| − | | + | |
| − | [https://translate.apache.org/da/aoo40/translate.html#unit=12977489 Example unit=12977489]
| + | |
| − | | + | |
| − | File: <tt>starmath/source.po</tt>
| + | |
| − | | + | |
| − | The string belongs to the formula editor MATH.
| + | |
| − | | + | |
| − | Location: <tt>smres.src#RID_DISTANCEDIALOG.7.2.string.text</tt>
| + | |
| − | *<tt>smres.src</tt>: "smres" perhaps stands for "star math resource".
| + | |
| − | *<tt>RID_DISTANCEDIALOG</tt> The string belongs to a 'distance dialog'.
| + | |
| − | *<tt>.7.2</tt> It is a multi-part dialog. On the first part choose the 7th string and in the next part the 2nd string.
| + | |
| − | *<tt>string</tt> "string" is rather generic, here it is an item in a drop-down list.
| + | |
| − | | + | |
| − | '''3'''
| + | |
| − | | + | |
| − | [https://translate.apache.org/da/aoo40/translate.html#unit=12980472 Example unit=12980475]
| + | |
| − | | + | |
| − | File: <tt>svx/source/sidebar/paragraph.po</tt>
| + | |
| − | | + | |
| − | The string belongs to something with paragraphs and is part of the sidebar.
| + | |
| − | | + | |
| − | Location:<tt>ParaPropertyPanel.src#RID_SIDEBAR_PARA_PANEL.TBX_LINESP.BT_BTX_LINESP.toolboxitem.text</tt>
| + | |
| − | | + | |
| − | *<tt>ParaPropertyPanel.src</tt> The string is in the paragraph panel of the Properties deck.
| + | |
| − | *<tt>RID_SIDEBAR_PARA_PANEL</tt> A resource identifier for the paragraph panel of the sidebar.
| + | |
| − | *<tt>TBX_LINESP</tt> It belongs to the toolbox ''line spacing''. The property panel has several toolboxes, in most cases drawn in a little bit lighter color with a hairline border. Such toolbox has an internal titel text, but that text is not localized and does not show up on Pootle.
| + | |
| − | *<tt>BT_BTX_LINESP</tt> There exist no general rule how to design identifiers. The position in the string shows you, that it is a toolbox item. A toolbox item can be a simple button, but may contain more controls including metric fields.
| + | |
| − | *<tt>toolboxitem</tt> The string is a kind of title for the toolboxitem, but it is only visible as simple tooltip. You need to hover with the mouse over the icon to see the string.
| + | |
| − | | + | |
| − | '''4'''
| + | |
| − | | + | |
| − | [https://translate.apache.org/da/aoo40/translate.html#unit=12981827 Example unit 12981827]
| + | |
| − | | + | |
| − | File: <tt>sw/source/ui/app.po</tt>
| + | |
| − | | + | |
| − | In this case you not really lucky. "app" indicates, that it is a collection of strings which belong to more or less independent items. At least you know from the part <tt>sw</tt>, that it belongs to Writer.
| + | |
| − | | + | |
| − | Loation: <tt>mn.src#MN_TEXT_ATTR.MN_FORMAT_LINESPACE.menuitem.text</tt>
| + | |
| − | *<tt>mn.src</tt> "mn" derives from menue.
| + | |
| − | *<tt>MN_TEXT_ATTR</tt> It is a menu for text attributes
| + | |
| − | *<tt>MN_FORMAT_LINESPACE</tt> A submenu for line spacing
| + | |
| − | *<tt>menuitem</tt> It is a text, that is shown in a menu. If you looked into the source file, you would guess that it is the context menu of text in Writer.
| + | |
| − | | + | |
| − | '''5'''
| + | |
| − | | + | |
| − | [https://translate.apache.org/da/aoo40/translate.html#unit=12969066 Example unit 12969066]
| + | |
| − | | + | |
| − | File:<tt>officecfg/registry/data/org/openoffice/Office/UI.po</tt>
| + | |
| − | | + | |
| − | This belongs to the Configuration data. They will be stored in the installation directory in share/registry. The user configurations extend these settings.
| + | |
| − | | + | |
| − | Location:<tt>GenericCommands.xcu#..GenericCommands.UserInterface.Commands..uno_SpacePara1.Label.value.text</tt>
| + | |
| − | *<tt>GenericCommands.xcu</tt> This file contains those commands, which are available in more than one module. For example "save the document" is available in all modules. The file format is XML.
| + | |
| − | *<tt>.GenericCommands.UserInterface.Commands.</tt> The elements in the xml format are nested nodes. Compare it with the source extract shown below.
| + | |
| − | *<tt>uno_SpacePara1</tt> This is the inner node. It is the name of the command. The underscore stands in place of a colon.
| + | |
| − | *<tt>Label</tt> and <tt>value</tt> correspond directly to the notation of the xml file.
| + | |
| − | <syntaxhighlight lang="xml">
| + | |
| − | <oor:component-data oor:name="GenericCommands" ...>
| + | |
| − | <node oor:name="UserInterface">
| + | |
| − | <node oor:name="Commands">
| + | |
| − | <node oor:name=".uno:AVMediaPlayer" oor:op="replace">
| + | |
| − | <prop oor:name="Label" oor:type="xs:string">
| + | |
| − | <value xml:lang="en-US">Media Pla~yer</value>
| + | |
| − | </prop>
| + | |
| − | <prop oor:name="Properties" oor:type="xs:int">
| + | |
| − | <value>9</value>
| + | |
| − | </prop>
| + | |
| − | </node>
| + | |
| − | ...
| + | |
| − | <node oor:name=".uno:SpacePara1" oor:op="replace">
| + | |
| − | <prop oor:name="Label" oor:type="xs:string">
| + | |
| − | <value xml:lang="en-US">Line Spacing: 1</value>
| + | |
| − | </prop>
| + | |
| − | ...
| + | |
| − | </node>
| + | |
| − | </syntaxhighlight>
| + | |
| − | The part <tt>xml:lang="en-US"</tt> causes, that the string <tt>Line Spacing: 1</tt> is localized and shows up in Pootle.
| + | |
| − | | + | |
| − | The command name is used to reference the command. Such <tt>.uno</tt> commands are used in several places in the application.
| + | |
| − | * As Button in a toolbar. The string is shown as simple tooltip and as default text. It is always the same string used, regardless of the toolbar.
| + | |
| − | * As menu item. The string is used as menu item text. Consider this when translating the term, so that it does not become to wide.
| + | |
| − | * When you record a macro, the dispatcher uses the command name. Programmer uses it when writing extensions using the API.
| + | |
| − | * As reference for the extended tips in the built-in help.
| + | |
| − | * When you customize a toolbar, you see the command name in the lower part of the description.
| + | |
| − | | + | |
| − | == 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''>
| + | |
The new Pootle User Guide is "live" now. But you will find a lot of "ToDo"s and empty sections. Please help to complete the guide and to correct all the errors.
At the beginning of each page you find a template, that shows the TOC from the right sight. It is the same on every page and should therefore be easy to translate.
At the end of the page is a list of languages. These are shown automatically in the left column. The links itself are dummies, but will you help to find the form, when you translate the content.
