Pootle Guide

    From The Document Foundation Wiki
    Incomplete-document.svg

    This page was marked as abandoned.
    If you think you can contribute in creation of this page feel free to do it, but before that you should remove this template. If this page is completely unusable as is, and cannot be improved or used in any other way, then replace this template with a deletion request: {{delete|Unusable, abandoned page.}}.

    This page details the different sections displayed in Pootle UI and how to use them. The Pootle home page gives you information on how to get an account and access your project translation. You can use Pootle either as a online translation tool or as a repository for your translation and use Virtaal or OmegaT for example as offline translation tools.

    When logging on the site, if you have difficulties to find your language, click on the The Document Foundation - Pootle server on the upper left of the screen, you'll be bring the translation home page where you'll be able to select your language and/or the project you want to work on.

    On the top of the screen, there are three drop down lists for Overview, All Languages or All projects.
    Selecting French for example, will lead you to this page:

    Project page of a selected language

    On the home page, on the upper right, you can access your account once you are logged in.

    My Account

    When clicking on your login name, there is a drop down menu that let you chose between your Public Profile, Settings and Statistics:

    • Public Profile let you add your Full name and avatar, links to social media and a short bio
    • Settings is where you configure your translation preferences:
      • on the first tab, choose the number of lines displayed on the screen by entering a number in the Number of Rows field, by default it is 9. Interface Language is where you choose the language of the Pootle interface. If you do not choose a language, English will be the default language. Alternative Source Languages: you can display another language aside the English sources. For this, choose one or more (by holding Ctrl while doing a multiple selection) languages that you want to add. To remove a selected language, hold Ctrl while clicking on the language you want to remove and save your changes again.
    Screenshot Display a second source language above the English one
    Display a second source language above the English one
      • Save your changes by clicking on the Save button.
      • The next tabs Password is rather self explaining.
    • Statistics gives you statistics on your translation contributions over the month.

    Projects

    This page displays all the projects uploaded on the Pootle repository. Currently you can see six main projects which are:

    • Impress remote (Android)
    • Impress remote (iOS)
    • Localization for the 4.x.x product (UI and Help files)
    • Localization for the 5.x.x product (UI and Help files)
    • Localization from master (UI and Help files). These projects pertains to the new workflow we have settled and let you translate earlier in the process.
    • LibreOffice OnLine. The online version of LibreOffice.
    • Terminology
    • Website which contains the translation of the LibreOffice website templates in your language if your team runs a translated website.

    The columns in the list of projects more or less speak for themselves. However some details are given below with the projects details, that have a similar list.
    If you need a project to be added for translation in your language, ask the Pootle administrator for it.

    Projects details

    If you enter a project, you will see a list view of the all the .po files to be translated. (On top there are some buttons - more on that below)
    Each file has a line which can be green, light green or gray depending on the completion of the translation. Mouse-over shows some statistics. There are the folowing columns.

    • Progress a progress bar, indicating what has been done.
    • Total the total of words contained in the directory.
    • Last update the last time the project has been updated
    • Need translation the number of words to be done. By clicking on the number, you directly access those words
    • Suggestions are the suggestions made by other members of your language team. If you have the correct permissions, you are able to accept or refuse those. Clicking on the number to go to those words.
    • Last activity mentions the team member that did the latest translations.

    At the left side of the bar at top there is the Browse button with access to Browse, Translate, Terminology and (permissions allowing) Permissions. Below is a bar that can be extended with the + at the left side.
    At the left of the screen is a handle with double arrow for down- and uploading files.

    Downloading po-files

    If you have selected a specific project, for example libo50_help/, then there is a little handle (with double arrow) at the right side, that allows you to hide or display a panel. This panel contains links to download and upload offline translations, depending on your rights. The drop down list below the Upload translation link allow you to upload files using the name of another team member.

    Screenshot Panel to download or upload off line translations

    Before going further, lets have a look to a very important area, the checks

    Checks

    Checks are scripts run on the files to detect different sort of errors, we detail them below.

    You can access the checks by clicking the little cross at the most left part of the progression bar. The critical ones which are mandatory to fix are displayed at the top of the overview in a red bubble, or listed by directory in front of them, still in the red bubbles. Clicking on any of them will filter and display the strings needing to be fixed.

    The different types of checks run are:

    • Critical: you have to correct those failing checks because they can corrupt the build or the user interface of LibreOffice. Pootle sometimes reports false positive depending on your language, but please check anyway that there is no real positive in your translation.
    • Functional: will affect the user experience, so this is also an important part where you have to correct your translation.
    • Cosmetic: well, they are cosmetic but they will improve the general quality of your translation, so when you have time, please take a look at them too.

    The Failing checks displayed may vary depending on the existent failings in your translation. To correct them, just click on the name like printf() or Invalid XML (or the number behind them) to access the concerned strings. Correct them, if needed, and once done, click Next at the bottom right of the screen until Pootle notifies you that you are over. When you have corrected all the strings contained in one category of checks, the name of this category will disappear from the list.

    If you find that the failing check is a false positive of the tested string, you can override it by clicking on its label in the right area of the editor, but if the template is later updated, the string will be marked as a failing check again. This is to ensure that the new translation is tested again for any possible issues.

    Search

    The Search field allow you to retrieve strings or words in the current displayed directory. When you click in the field to enter the words to search for, a submenu is displayed with five checkboxes:

    • Source: you will run the search on the English strings only in the directory.
    • Target language: you will run the search on the strings in your language in the directory.
    • Comments: you will search through the comments you or others have left in the Comments section of the strings.
    • Location: you can enter the path for a specific location here.
    • Exact Match: the search will match exactly the string you entered

    Pressing Ctrl + ⇧ Shift + S will place the focus in the Search field without displaying the submenu. Press ↵ Enter once you have typed the words you are searching for to run the search, or click on the little icon on the right of the field.

    Some hints on this field:

    • you can enter several words, they will be considered as linked by a logical AND operator.
    • there is no discrimination by using either using logical OR or NOT operators.
    • the search is not case sensitive. It does not matter if you enter Options or options or opTions.
    • you can enter accelerators keys such as ~ or _ in the field, like _word or wo~rd.
    • you can not begin your search by a blank character. You will obtain no result in that case.

    As you can see, this search field is pretty limited. You can find Grep commands documented on this page if you are using Linux.

    Note: each string has a KeyID reference that you can use for the search. This KeyID is added as a comment on the Pootle editor, see the screenshot below, where the KeyID of the string is 9LgFW.

    Screenshot KeyID in comment
    Comments area containing the KeyID of the string

    Translation

    The Continue Translation on the top will lead you to all untranslated strings in the projects. Clicking into the Need Translation column on one of the blue bubble showing the number of words to translation will lead you also to the untranslated strings in that project. The same will happen if you display the files pertaining to a project. You can enter the tree of files at each level. At the end, the editor will be displayed and this is where you will do your localization work, as a localizer or as reviewer or by adding suggestions. When you click on a file, the editor is displayed prompting for your translation.

    Depending on the checks, the background of the area will be light blue or light red in case there is failing checks that you need to pay attention to.

    You can add suggestions from LocalTM which is a memory generated from LibreOffice translation. Suggestions are displayed below the translation area.

    This editor area, when you work on a string, can be divided in three main parts. See the screenshot below: on the left, the elements that will help you (such as path file, comments and terminology suggestions), on the middle the source string and your translation, on the right the submission button and failed checks if any.

    Screenshot string area in Translate tab
    String area on the Translate tab

    Left area

    The Left area gives you some hints on the context and on the location of the file:

    • the first path at the very top of the editor is where the file is located in the tree. In our example it is libo_help/swriter.po, so it means in the help directory and the file is named swriter.po, the number of the unit in the database is #92548984
    • the Context gives indication on where the string is situated in the source code and gives an indication on the nature of that string. When you are used to this, you can retrieve some context from here too.
    • the Comments here is the KeyID reference of the string in the interface. This reference is unique for each string.
    • the Terminology is a Pootle project that you can create from an existing translation. It is a simple .po file. These are displayed as suggestions for words that match the terminology when the translation exists. If you click on the suggestion label, it will insert the translated word directly in the edit field.
    screenshot left area of editor
    Left area of the editor, giving file path and context

    Central area

    The Central area is the editor itself where you enter your translation. If another source language is activated, it will be displayed above the English source.

    • when there is a tag in the source string, like <bookmark_value> or </bookmark_value>, clicking on this tag will transfer it automatically to the target (where you enter your translation) at the cursor position.
    • on the very top right of this area, there is a small icon, on the right of Report a problem with this string that allows you to copy the source string into the editor. You can use it when a string is a variable for example and does not differ from the source.
    • below the editor frame, there are three icons, the first one shows the timeline of the string, the second one Add Comment opens a field where you can enter a comment. This comment unfortunately will not be retained when the strings are uploaded to another project if you enter it from here. Once the comment is entered, click the Submit button below. The third icon Raw view changes the preview of the translated string.
    screenshot editor area
    Editor area

    Right area

    The Right area contains a Submit button, but you can also press Ctrl + ↵ Enter to submit your translation and go to the next string.

    • the little checkbox Needs work is checked if the string is marked as fuzzy. If you need to come back to it, you can also mark it as a bookmark.
    • if you click on the Suggest link, the Submit button will change to a Suggest button and the editor will switch in Suggestions mode. The translation will appear as a suggestion that needs to be approved. You can also use Ctrl + ⇧ Shift + Space to shift from one mode to the other. Strings that are entered as suggestions can be accessed directly from the tree view too.
    • Failing checks if any are displayed above the Submit button, see the screenshot below for an example.
    screenshot of the right area
    the submit area with Failing check displayed
    • the String number that follows is the direct reference to the string in the database. This is useful if you have to discuss the string with your team as you can share its link directly.

    Top Bar

    At the top of the screen of this Translate tab page, a Top bar gives you several indications:

    screenshot of status bar
    Status Bar giving several indications and filter possibilities
    • on the left, the Search field is the same as the one previously discussed.
    • the drop down menu on the right of the Search field lets you choose from list between several options: needs work, suggestions, overwritten suggestions, untranslated, etc. The screenshot above shows a filter by Checks.
    • depending on the filter you have chosen, another drop down list may be displayed. In the screenshot above, once filtered by Checks, you will be able to choose between the different Checks: Critical, Functional, Cosmetic, if any.
    • the button Default order lets you navigate to the newest or oldest string.
    • the next field is the string number you are on. The string count is also displayed. To navigate to another string, enter its number in the field.
    • then the arrow buttons allow you to navigate to the previous or next string. You can press Ctrl +  or Ctrl +  as an alternative.

    Terminology

    The Terminology file is a .po file that you can upload and manage on Pootle. The translated words it contains will be shown as suggestions in the Translate area of the string you are working on. This file can also serve as a reference for the documentation team, translating the guides or creating new documentations.

    Creation

    You first have to ask the Pootle administrator to create the project on Pootle. Then you can upload an existing .po file using the Upload button on the right of the page, or extract a new terminology file from the existing localization files on Pootle using the Terminology tab page. We will discuss this last option later.

    Some hints on the file creation:

    • sometimes people do not distinguish between the terms terminology and glossary.
    • when you create an entry, make it as simple as possible: object and not an object for example.
    • if you add a comment to an entry, this comment will be displayed as a tooltip in the editor.
    • you can add context information to the source term, for example view (verb) or view (noun), but don't add it to the target text (your translation), because it will be also inserted when you click on the suggestion label in the editor.
    • an entry can contain up to 30 characters.
    • when terminology is active, it is performed in real time on your translation, so be careful of the size of your terminology file, because it can affect the performance if you have too many terms.

    Management

    You can manage the file directly using the Pootle editor under the Translate tab page, by clicking on the project link and manage the terms. From here you manage the translation of the file.

    There is also a Terminology tab page that allows you to display the file and add comments to the source language, as said above. This tab page also allows you to extract a new terminology file by clicking on the link You can regenerate a glossary from scratch. But you will not be able to change the translation from here. It is only possible on the Translate tab page.

    • the little i icon in front of the translation indicate some paths to files where the word is found and the number of occurrences.
    • clicking on the little callout at the right of the source field will open a comment field where you can enter information. The KeyID of the string is also entered here, so do not remove it.
    • the checkboxes on the very right of the page allow to delete string entries from the .po file.
    • you need to save your changes with the Save changes button at the bottom left of the page.
    screenshot terminology entry
    Terminology entry showing comment and information

    Checking the translation context (Help pages only)

    For the translation of LibreOffice Help you can display the Help page that contains the string to translate. The information is available in Pootle UI but you must pick the information and build the URL of the Help online instance.

    Pootle-Image.png

    In the example above, the URL is

    https://helponline.libreoffice.org/RR/en-US/source/text/AAAA/BB/CCC.html

    Where

    • RR is the release (6.1, 6.2, 6.3)
    • AAA is the module name (smath, shared, scalc, sbase, sbasic, swriter, sdraw, or simpress)
    • BB is the folder
    • CCC is the help file, which extension is now html


    Suggestions

    Depending on the permissions given to team members, some of them may be able to make suggestions but are not able to translate the strings directly. We have seen above that it is possible to switch between translation mode and suggestion mode by using Ctrl + ⇧ Shift + Space.

    When there are any suggestions made, it will be indicated above the translation progress bar as a link: Review suggestions (xx left), where xx is the number of suggestions remaining to be reviewed. It will be also indicated in the tree view in the Suggestions column. You only have to click on one or the other number to be able to accept or refuse the suggestions.

    The suggestions are displayed below the comments field, and the differences between the original string and the suggested one are highlighted in the suggestions field. To accept a suggestion, click the green check, it will replace the original string in the editor field. If you want to discard the suggestion, click the red cross, and the suggestion will be deleted.

    screenshot managing suggestions
    Managing suggestions

    In the terminology file, it is also to vote on a suggestion by clicking the small star on the right of the suggestion area. When it is clicked the star becomes yellow and the number of votes are reported inside. To remove your vote, only click the star again.

    screenshot showing votes on suggestions
    Votes on suggestion

    News

    The News tab allows members to post information about the current project or directory to the Pootle members of the project. You can send this news by e-mail too.

    Some actions on the project are also reported as news, even if you do not publish them on this tab, and will appear in the News tab in the form of:

    Sat 07 Sep 2013 04:21:19 PM UTC
    sophie uploaded a file to LibreOffice 4.1 – UI [French] 
    Before upload: 29799 of 29799 strings translated (0 fuzzy). 
    After upload: 29799 of 29799 strings translated (0 fuzzy).  
    

    This way you can monitor activities on your project, for example when the template is updated, it will also appear here.

    Permissions

    To see this Permissions button, the member has to have the project, translator or administrator rights. The Permissions button is located in the drop down menu under the default Browse button. Click on the little arrow near it to display the entries of the list. Permissions entry in the drop down list

    There are two special permissions on Pootle for Nobody and Default. The user Nobody represents any non-logged in user, and the user Default represents any logged in user.

    Be careful: even as an administrator of your language, you can remove your own permissions. If it happens, kindly ask the Pootle administrators to give them back to you (we all have done it once ;-)

    The different permissions are:

    • Can add directory: gives the possibility to add a directory to a project.
    • Can administrate a translation project: gives the possibility to manage the rights for other members on the translation projects.
    • Can download archives of the translation project: allows to download the zip of .po files of the project.
    • Can change directory: (to be checked) allows to change the directory of a file.
    • Can commit to version control: allows to commit to the code repository. This is not used in our translation process.
    • Can delete directory: gives the possibility to delete a directory from a project.
    • Can overwrite translations on uploading files: allows to overwrite files instead of merging them when uploading them after off line translation.
    • Can review suggestions: allows to accept or reject suggestions made.
    • Can make a suggestion for a translation: allows members to make suggestions on a string
    • Can submit translation: allows to submit translation directly without the review of another member.

    To set permissions to a member, select the permission, or hold Ctrl to do a multiple selection and click the Save changes button. Ticking the check box on the right will delete the current user.