Difference between revisions of "Translating the Gramps User manual"

From Gramps
Jump to: navigation, search
(Links to wiki manual)
(Where to begin...?: they use uppercase letters for Gimp)
 
(58 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{languages}}
+
{{languages|Translating the Gramps User manual}}
An explanation of how you can translate the [[Gramps 3.3 Wiki Manual|GRAMPS manual]]. This manual is also available from within GRAMPS using the {{man key press|F1}} key (which opens this manual in a browser window), or from the help menu.
+
{{stub}}
 +
{{man note|The user manual|is also available from within Gramps using the {{man key press|F1}} key (which opens this manual in a browser window), or from the help menu.}}
 +
An explanation of how you can translate the [[User manual|Gramps User manual]].
  
 
==Getting started==
 
==Getting started==
  
Translating GRAMPS' documentation into a new language is a long, tedious, and boring process, just like with any complex text :-)
+
Translating Gramps' documentation into a new language is a worthwhile process and the Gramps team thanks you.
  
Since GRAMPS version 3.0 the documentation was moved completely to this wiki. So for translation you don't need to use or even install any fancy applications to help us. You can use your browser and start immediately. Just go to the [[Gramps 3.3 Wiki Manual|User Manual]] page, click on your language. You should could keep the english manual open to check if there is a help page missing.
+
Since Gramps version 3.0 the documentation was moved completely to this wiki. So for translation you don't 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 [[Help:Contents|wiki help page]] will help you editing wiki pages. This wiki uses the [http://www.mediawiki.org/ MediaWiki] software, which is the same that is used by [http://en.wikipedia.org/wiki/Wikipedia Wikipedia], so it could feel familiar.
 
The general [[Help:Contents|wiki help page]] will help you editing wiki pages. This wiki uses the [http://www.mediawiki.org/ MediaWiki] software, which is the same that is used by [http://en.wikipedia.org/wiki/Wikipedia Wikipedia], so it could feel familiar.
Line 12: Line 14:
 
==Translating==
 
==Translating==
  
* Figures: localized screenshots are nice in the localized manual
+
===Recommendations===
** If you can provide figures on your own this is great. Upload them to this wiki with the following naming convention: <code>figure_name_zz.png</code> (<code>zz</code> is your language code). If the figure is language independent just call it <code>figure_name.png</code>.
+
Recommended that when updating any of the user manuals:
** A command to take screenshots that works for me, is by using imagemagick (should be installed with every linux distribution, if not, get it): <pre>import -quality 100 -trim -delay 200 -resize 500 -density 100x100 -frame -channel RGB -depth 8 screenshot.png </pre>This creates a fully compressed (<code>-quality 100), timed screenshot after 2 seconds (<code>-delay 200</code>) of size 500 pixels wide (<code>-resize 500</code>), with resolution 100 (<code>-density 100x100</code>), with the window frame attached (<code>-frame</code>) in RGB mode (<code>-channel RGB</code>) and bbp 24 (<code>-depth 8</code>). This creates images of 5 inches wide, which fit nicely on a book page, as well as on a HTML page.
+
====Where to begin...?====
** If it's too much trouble for you, just let us know and perhaps somebody else will do it for you. Fortunately, one does not have to speak the language to make screenshots :-)
+
* Translate the page that will help your compatriots configure Gramps so that it shows your language.
** For maintenance, it could be more easy to follow a naming scheme :
+
* For your own reference and understanding, a good place to start is to translate the [[Gramps_{{man version}}_Wiki_Manual_-_Preface#Typographical_conventions|Preface and Typographical Conventions]] page. This will also giving your compatriots a better understanding of how to interpret the context of content styling in the wiki. <br />Verify that your language begins to appear by default and shows up as an option in the Languages bar.<br /> ''Then link the translation on your [[Special:MyPage|WikiContributor "User" page]]. You will find it a useful reference during future translations.''
*** filename-''{gramps version number}-{locale}''.png <pre>Mainwin-33-fr.png</pre>
+
* Translating the ''[[Gramps_{{man version}}_Wiki_Manual_-_Main_Window|Visual Guide to the Gramps Interface]]'' involves more commitment than many pages. There are a lot of screen captures with annotations to translate. [https://www.gimp.org/ GNU Image Manipulation Program (GIMP)] is a good tool for adding the annotations.
*** filename_''{gramps version number}_{locale}''.png <pre>Mainwin_33_fr.png</pre>
+
* Gramps uses [https://pyenchant.github.io/pyenchant/ PyEnchant] for Spellcheck and Grammar checking. The Dictionary and Affix files are available from a variety of [https://pyenchant.github.io/pyenchant/tutorial.html#provider-ordering providers] (such as aspell, ispell and myspell). Find the Dictionary and Affix files for your language and install the files in the right place for Gramps to use them. Translate the instructions.
 +
* Translate the re-usable Annotations used in the wiki:
 +
** [[Template:Languages|label for the Languages bar]]
 +
** [[Template:Stub|Stub template]]
 +
** [[Template:Out_of_date|Out of Date notice]]
 +
** [[Template:Cleanup|Cleanup notice]]
 +
** [[Template:Third-party_addon|Third-party addon notice]]
 +
** [[Template:Grampsmanualcopyright|Copyright template]]
 +
* [[Gramps:Using_Gramps_templates|the 8 subsections of the Using Gramps portal]]
 +
* [[Howto:Change the language of reports|Choosing a different Language for Reports]]
 +
 
 +
====Tools and Configuration====
 +
[[File:WeblateSearch.png|353px|thumb|right|[https://hosted.weblate.org/projects/gramps-project/gramps/#search 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 [https://hosted.weblate.org/projects/gramps-project/gramps/#search search the Weblate translations]. (i.e., searching for the phrase <code>source:"Relationship Information" AND language:fr</code> finds French translation: "Information sur la relation". Clicking that translation says that that phrase was found that phrase in the <code>editfamily</code> 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.
 +
 
 +
===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:
 +
<pre><!--is in the process of being--></pre>
 +
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.
 +
{{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.
 +
}}
 +
<pre>{{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 &lt;!--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.
 +
}}</pre>
 +
 
 +
===Screenshots===
 +
Localized screenshots (aka: figures ) are useful for the localized manual.
 +
* If you can provide screenshots that would be great. Upload them to this wiki with the following naming convention/scheme (<code>locale</code> is your two letter language code):
 +
** filename-''{gramps version number}-{locale}''.png  eg: <code>Mainwin-{{Stable branch}}-fr.png</code>
 +
** filename_''{gramps version number}_{locale}''.png  eg: <code>Mainwin_{{Stable branch}}_fr.png</code>
 +
** If the screenshot/figure is language independent (such as an unlabeled icon) then just call it <code>figure_name-{{Stable branch}}.png</code>.
 +
* The Linux tool called imagemagick has proven very effective 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 : <pre>import -quality 100 -trim -delay 200 -resize 500 -density 100x100 -frame -channel RGB -depth 8 screenshot.png </pre>This creates a fully compressed (<code>-quality 100</code>), timed screenshot after 2 seconds (<code>-delay 200</code>) of size 500 pixels wide (<code>-resize 500</code>), with resolution 100 (<code>-density 100x100</code>), with the window frame attached (<code>-frame</code>) in RGB mode (<code>-channel RGB</code>) and bbp 24 (<code>-depth 8</code>). This creates images of 5 inches wide, which fit nicely on a book page, as well as on a HTML page.
 +
* If it is too much trouble for you, just let us know and perhaps somebody else will help you. Fortunately, one does not have to speak the language to make screenshots :-)
 +
 
 +
 
 +
[[Screenshots]] - gallery of available references for screenshots in different languages and past versions.
  
 
==Links to wiki manual==
 
==Links to wiki manual==
  
To have your recently translated manual available from within GRAMPS. You need to activate the manual by editing the following file: '''[https://gramps.svn.sourceforge.net/svnroot/gramps/trunk/src/GrampsDisplay.py GrampsDisplay.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 [[Using_the_bug_tracker |Bug tracker]].
+
Your recently translated manual can be made available from within Gramps. When the localized wiki pages pages appear from clicking the {{man button|Help}} button in Gramps dialogs or pressing the {{Man key press|F1}} key, the manual is considered [[User_manual#Enabled|enabled]] or activated.
 +
 
 +
You activate the manual by editing the following file: '''[https://github.com/gramps-project/gramps/blob/master/gramps/gui/display.py 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 [[Using_the_bug_tracker |Bug tracker]].
  
On line 32 of that file, you see:
+
In that file, you see:
  
MANUALS = {
+
<pre>
 +
MANUALS = {
 
     'nl' : '/nl',
 
     'nl' : '/nl',
}
+
}
 +
</pre>
  
 
This maps a language code to the extension used on the wiki, so to add french, change this to:
 
This maps a language code to the extension used on the wiki, so to add french, change this to:
  
MANUALS = {
+
<pre>
 +
MANUALS = {
 
     'nl' : '/nl',
 
     'nl' : '/nl',
     'fr': '/fr',
+
     'fr' : '/fr',
}
+
}
 +
</pre>
  
*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.
+
*Every '<code>manual|...</code>' 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.
+
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 [http://translate.sourceforge.net/wiki/toolkit/txt2po txt2po].
+
*You should be able to edit directly on wiki or using tools like [http://translate.sourceforge.net/wiki/toolkit/txt2po#mediawiki txt2po] and [https://weblate.org/ Weblate].
  
Also previous gettext file for the manual and [http://en.wikipedia.org/wiki/Translation_memory Translation Memory] may help you to upgrade deprecated/old gettext files.
+
Also previous gettext file for the manual and [https://en.wikipedia.org/wiki/Translation_memory Translation Memory] may help you to upgrade deprecated/old gettext files.
  
 
==Possible improvement==
 
==Possible improvement==
  
A project like [http://www.gnucash.org/ GnuCash] provides a complete web site environment by using gettext files, see [http://svn.gnucash.org/repo/htdocs/trunk/README README file] and current [http://svn.gnucash.org/repo/htdocs/trunk/ environment].
+
A project like [http://www.gnucash.org/ GnuCash] provides a complete web site environment by using gettext files, see [https://github.com/Gnucash/gnucash/blob/master/README README file] and current [https://github.com/Gnucash/gnucash environment].
  
 
[[Category:Translators/Categories]]
 
[[Category:Translators/Categories]]
 
[[Category:Developers/General]]
 
[[Category:Developers/General]]
 +
[[Category:WikiContributors|Translators/enabled manual]]

Latest revision as of 21:12, 8 October 2023

Gramps-notes.png

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


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.

Getting started

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

Since Gramps version 3.0 the documentation was moved completely to this wiki. So for translation you don't 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 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

Recommended that when updating any of the user manuals:

Where to begin...?

Tools and Configuration

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

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.

Gnome-important.png

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.

  • If you can provide screenshots that would be great. Upload them to this wiki with the following naming convention/scheme (locale is your two letter language code):
    • filename-{gramps version number}-{locale}.png eg: Mainwin-52-fr.png
    • filename_{gramps version number}_{locale}.png eg: Mainwin_52_fr.png
    • If the screenshot/figure is language independent (such as an unlabeled icon) then just call it figure_name-52.png.
  • The Linux tool called imagemagick has proven very effective 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.
  • If it is too much trouble for you, just let us know and perhaps somebody else will help you. Fortunately, one does not have to speak the language to make screenshots :-)


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

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.