Open main menu

Gramps β

Translating the Gramps User manual

Gramps-config-language.png Languages: 

English  • עברית

Gramps-notes.png
The user manual

is also available from within Gramps using the F1 key (which opens this manual in a browser window), or from the help menu.

An explanation of how you can translate the Gramps User manual.

Contents

Getting started

Translating Gramps' documentation into a new language is a worthwhile process and the Gramps team thanks you.

Documentation was moved completely to this wiki starting with Gramps version 3.0. So for translation you do not need to use or even install any fancy applications to help us. You can use your browser and start immediately. Just go to the User manual page, select the current manual and then click on your language. You should could keep the English manual open to check if there is a help page missing.

The general wiki help page will help you with editing wiki pages. This wiki uses the MediaWiki software, which is the same that is used by Wikipedia, so it could feel familiar.

Translating

Recommendations

We recommend that before updating any of the user manuals:

  • You have identified what your Languages two letter code is.
  • You are familiar with Mediawiki wikitext/wiki markup/wiki code and templates and have practiced editing on Wikipedia for a little while at least.

Where to begin...?

Practice

Let's practice by creating and translating a version of this page to learn what needs to be done for the user manual.

Start by initially creating a new page in your language for the translation:

  • Start with the English version of the page name and add add a fowardslash / and then your Languages two letter lowercased code xx to end of the URL /xx eg:
https://gramps-project.org/wiki/index.php/Translating_the_Gramps_User_manual

becomes 

https://gramps-project.org/wiki/index.php/Translating_the_Gramps_User_manual/de

Then press Enter and wiki will show the following message:

There is currently no text in this page. You can search for this page title in other pages, search the related logs, or create this page.

Select the last link create this page. in the message for the page editor to open a blank page ready for the initial text.

  • where you can then copy the contents of this English page by using the "edit" button at the top wiki page to access the raw wiki contents.
 

This article's content is incomplete or a placeholder stub.
Please update or expand this section.


Prepare the templates

Using what you learned above create translated versions of the first three User manual templates - as they will used on each of the user manual pages.

Then on your languages version this page that you previously created update the Languages Template to your languages version.

Start with the User manual index

Let's begin with the user manuals index page.

Follow the steps you practiced above

  • Start with the English version of the page name and add your Language code.
  • Copy the contents raw contents of the English version wiki page to your Languages page.
  • Change the pages English templates to use your language code
  • Translate the contents of the page.
Continue with the rest of User manual

Repeat this for the rest of user manual pages.

Optional final steps

  • Create screenshots in your Language ....
  • Use the wiki pages move option at top of the page to rename and move your English Languages version of the page name to your language as then it will leave behind a redirection from the English page that is used by the Gramps programs Help function (as the builtin in help only adds the two letter Language code to the English version of the page name)
  • links for non English user manuals don't always work because of translated title and redirection! use <span ID="Section_name"></span> wrapped around the relevant section title. eg:
  • Request that Links to wiki manual in the Gramps program be Enabled for your Language. F1 & help menu.
 

This article's content is incomplete or a placeholder stub.
Please update or expand this section.



Important re-usable Templates

Translate the following re-usable templates/Annotations used in the user manual and few used in general on the wiki:

Tools and Configuration

 
Weblate Search form
  • Use Gramps localized in that language as a reference and do not simply guess the words. Verify your translated text actually matches what the user will see in the standard localized Gramps installation. You can search the Weblate translations. (i.e., searching for the phrase source:"Relationship Information" AND language:fr finds French translation: "Information sur la relation". Clicking that translation says that that phrase was found that phrase in the editfamily code and lists the other nearby translated text. This includes Tips as well as labels.)
  • If the localized interface has a typo or incorrect translation, document the EXISTING interface. Do not mislead the user into expecting something else. They might waste time searching for an non-existent update.
  • Do not have any third party addons loaded. Use a vanilla version of Gramps unless documenting that particular addon.
  • Also, preferably use a fresh copy of the Example.gramps family tree for any screenshots in your preferred language.

Anchors and Links

Each heading line - no matter how many equal signs it contains - creates an anchor, which can be linked to. There are reasons to keep the English heading text together with the translated heading text. For example when using the Help button in a Gramps dialog window, it usually links to a specific section in a chapter in the manual. This link will typically refer to the English header text, but when running Gramps in another language, the link might not be available in the translated manual.

An example The User Manual chapter Navigation contains the section Using Gramplets. When translating the '=== Using Gramplets ===' section e.g. to Danish, the section header becomes '=== Brug af Gramplets ==='. To keep the English anchor together with the translated anchor, the English header text can be included in a span tag: 

=== Brug af Gramplets <span id="Using Gramplets"/> ===

The span tag will not be shown, when reading the manual page.

When keeping the English anchor, the page section can be referred to in different ways:

Da:Gramps_6.0_brugsanvisning_-_Navigation#Brug_af_Gramplets
Gramps_6.0_Wiki_Manual_-_Navigation/da#Using Gramplets

Shorthand links

When linking to a section on the same page you can use a short form of the link.

Both the full link [[Translating_the_Gramps_User_manual#Translating]] and the shorthand link [[#Translating]] links to the same section on this page.

Using the shorthand link makes the text more readable, when editing the manual page.

Handling of Translations Errors

Translation errors, typos and revisions are inevitable.

It is important that documentation describe software as it currently exists... not as it should be in a perfect world.

That acknowledgment of a localization problem in the wiki doesn't mean that the problem cannot or will not be fixed. Rather than patch the problem in documentation, file a translation bug report, see How to report bugs. A good bug report will also include a link to the wiki page that will need to be revised. The wiki page link gives the developer a second viewpoint of the nature of the problem. This helps if the bug report accidentally omits key information.

There is no requirement to pretend a problem doesn't exist while waiting for a fix. It is reasonable to annotate that the translation has the problem in the wiki without misleading the user into expecting something else.

You can make this annotation easier to eliminate after the bug fix. An English version Warning box like below can be inserted with the wiki code snippet that follows it. You might notice that the snippet has a chunk commented out: 

<!--is in the process of being-->

By moving the comment markers, you can re-cycle this same warning and easily update to inform that a Bug has been filed and when a correction was released. When the manual is rolled over for the corrected release, you can update the main text and any affected screenshots before removing the warning entirely.

 

An unfortunate translation in the Gramps 4.1.0 interface is documented above. A "localization" Gramps bug report 7854 has been filed... so any corrections (version 4.1.1) might make this warning obsolete.

The Gramps Wiki documentation is a community project. If you notice that documentation is: outdated, incomplete, entirely missing, or not yet translated into your native language; request a WikiContributor account and help us improve! Or join our volunteers translating the interface. 

{{man warn|1=[https://omniglot.com/language/phrases/hovercraft.htm My hovercraft is full of eels]|2=An unfortunate translation in the Gramps 4.1.0 interface is documented above. A "localization" Gramps bug report <!--is in the process of being-->{{bug|7854}} has been filed... so any corrections ''<small>(version 4.1.1)</small>'' might make this warning obsolete. 

{{WikiContributorRecruiting}} Or join [[Portal:Translators|our volunteers]] translating the interface.
}}

Screenshots

Localized screenshots (aka: figures ) are useful for the localized manual.

Create the screenshots

If you can provide screenshots that would be great as fortunately, one does not have to speak the language to make screenshots :-)

If you need help, ask on the Gramps forum and somebody will help you.

Use the following file naming convention/scheme:

  • {filename}-{gramps version number}-{locale}.png eg: Mainwin-60-fr.png
    • Where filename is always exactly the English filename
    • gramps version number - Is the current two digit release number eg: Currently version 60
    • locale is your two letter language code. Use the Language code table on Wikipedia, the free encyclopedia.
    • .png - always use this file type to save the images as.
  • If the screenshot/figure is language independent (such as an unlabeled icon) then just call it figure_name-60.png.


Screenshot advice
You can use the Linux tool called imagemagick for taking Gramps screenshots for this wiki. (imagemagick should be installed with every Linux distribution. If not with your installation, get it!) Invoke the preferred command options by using : 
import -quality 100 -trim -delay 200 -resize 500 -density 100x100 -frame -channel RGB -depth 8 screenshot.png
This creates a fully compressed (-quality 100), timed screenshot after 2 seconds (-delay 200) of size 500 pixels wide (-resize 500), with resolution 100 (-density 100x100), with the window frame attached (-frame) in RGB mode (-channel RGB) and bbp 24 (-depth 8). This creates images of 5 inches wide, which fit nicely on a book page, as well as on a HTML page.


Also see:

  • Screenshots - gallery of available references for screenshots in different languages and past versions.

Upload the screenshots

You can learn to upload files to this wiki by following the advice on:

Make sure to complete the "Summary" before uploading the file to wiki.

Links to wiki manual

Your recently translated manual can be made available from within Gramps. When the localized wiki pages pages appear from clicking the Help button in Gramps dialogs or pressing the F1 key, the manual is considered enabled or activated.

You activate the manual by editing the following file: gramps/gui/display.py to contain your language code, you may also contact the developers of Gramps by opening a Feature request for the new language on the Bug tracker.

In that file, you see: 

MANUALS = {
    'nl' : '/nl',
}

This maps a language code to the extension used on the wiki, so to add french, change this to: 

MANUALS = {
    'nl' : '/nl',
    'fr' : '/fr',
}
  • Every 'manual|...' entry in the gramp.pot file refers to a section in the manual, so make sure to use good section headings so this does not change too much over time.

Note that reports/tools link to a section in the page with the same name as the report name in Gramps.

  • You should be able to edit directly on wiki or using tools like txt2po and Weblate.

Also previous gettext file for the manual and Translation Memory may help you to upgrade deprecated/old gettext files.

Possible improvement

A project like GnuCash provides a complete web site environment by using gettext files, see README file and current environment.

Retrieved from "https://gramps-project.org/wiki/index.php?title=Translating_the_Gramps_User_manual&oldid=130007"