Punt - a multi-language 3D world viewer

Home Release Notes Download Plugins Support/Community For Translators CVS Policies SourceForge page

For Translators

Punt has been internationalized, using GNU gettext, in order to support multiple languages. Punt always supports English. This page will explain the basics of what you need to do if you would like to help the Punt project by creating a new language translation file.

Getting started

1. You will need to be fluent in both English and the language of the translation.
2. Join the Punt-globalization mailing list.
3. Have some understanding of how GNU gettext works.

GNU gettext

The 'short version':

• In the Punt source code we "mark" any text string that should be translatable.
• We use xgettext (one of the gettext tools) to process the Punt source code, to extract all the marked text strings.
• xgettext produces a POT file, which basically consists of pairs of lines where one line is the extracted text string, and the next line is an empty translated string.
• After adjusting a few of the POT file's headers we either:
  • create a PO file for the desired language by making a copy of the POT file
  • create a PO file for the desired language by merging an existing PO file with the POT file, in order to preserve existing translations as much as possible
• We name the PO files according to the language that will be used for the translation. For example, de.Punt.po is for German, de-AT.Punt.po is for German (Austria).
• A translator edits the PO file for their language, and enters the translation for each text string.
• Once a translator is finished their translation, they need to send us their updated PO file.
• We use msgfmt (one of the gttext tools) to process the PO file into a DLL file.
• The DLL file is made available for people to use with Punt. When placed in the proper subdirectory of Punt's "languages" directory, the new language translation is available for use with Punt - no changes to the Punt program are required.

To get a more detailed understanding of GNU gettext, you can read the GNU gettext tools manual. There are parts of the manual that do not apply to how gettext is used with Punt, and with poEdit.

poEdit setup

PO files are plain text, so any editor could be used, but there may be issues of proper character set support. We suggest translators use poEdit to edit PO files.

After poEdit is installed, you need to change some of it's settings:

1. On the File menu select Preferences. On the Personalize tab enter your full name, and email address.
2. On the Editor tab, "Automatically compile .mo file on save" should be unchecked. For CR/LF conversion the "Line endings format" should be Unix, and "Don't change format of existing catalogs" should be checked.
3. On the View menu, "Show comment window" and "Show automatic comments window" should be checked.

Coordination

Use the Punt-globalization mailing list to coordinate working on your translation - there is no point in having two people working on the same language translation. You can search the mailing list archives to see if the language you are interested in has been discussed or if someone is already working on it's translation.

If you are starting a new translation, send an email to the mailing list so people know what you are working on.

Getting the PO file

Eventually we plan to setup an automated method to help organize the Punt language files. For now, you can download this Punt 1.4.0 alpha2 POT file (11 KB ZIP). UnZip the file, and then rename Punt-1.4.0alpha2.pot to "ll-CC.Punt.po". The "ll-CC" is the Culture for your language, which you can get from this List of Cultures. For example, if you were going to do a German language file, the renamed file would be de.Punt.po and for German (Austria) it would be de-AT.Punt.po

If there is already a language file (e.g. German, or English(supported by default)) and you want to do a language file to deal with regional variations in the language (e.g. Austrian German(de-AT), or Jamaican English(en-JM)), you have three options:

1. Start with the above POT file. Go through and do translations for only those messages which have a different translation than in the 'region-neutral' language file. Because of how gettext works, when a user selects the regional language in Punt, a translated message will be obtained from the regional PO file, but if it's translation is missing in that file, it will get it from the 'region-neutral' language file. This is the preferred approach, because it minimizes the number of translations that the translator has to do to provide support for a regional language, and it's easy to keep track in the PO file of which messages have been translated into a regional variant.
2. Start with a copy of the PO file for the 'region-neutral' language. Currently, you will have to contact one of the project administrators to obtain that file. Go through and change the translations for those messages which have a different translation in the language's regional variation. This mixes translations for both the 'region-neutral' and 'region-specific' languages into one file, so it is not the best approach.
3. Start with the above POT file. Go through and do translations for all of the messages. We don't suggest this approach, because you will be wasting your time doing the translations for all the messages which have the same translation as in the PO file for the 'region-neutral' language file.

Doing the translation

• Load the PO file into poEdit.
• • If the PO file is for a new language translation, there will be no existing translated messages, and you will have to work your way through the entire file.
  • If you are doing an update to an existing language file, poEdit lists the untranslated messages at the top of the list of messages, then any messages marked as "fuzzy", then translated messages. You need to add translations for the new messages that do not have translations - these messages have been added to the PO file since the prior translation was done. A message that is marked as "fuzzy" is one which was previously translated, but for which the translation may no longer be valid. You need to review the messages that are marked as "fuzzy", and either correct the translation, or, if the existing translation is correct, mark the message as not being "fuzzy".
• Ampersand (&) characters in messages:
  • If the original message uses an ampersand in place of the word "and" (e.g. Latitude & Longitude), if it is suitable for your translation language, use an ampersand.
  • Try and avoid adding ampersand characters to translated messages if they don't exist in the original message.
  • In most cases where a message contains an ampersand (&) character it is because the message is text that is part of a menu, and the ampersand indicates that the next character is the keyboard shortcut key for that menu item. You may want/need to place the ampersand in front of a different character in the translated message, but that will change the keyboard shortcut for that menu item. You need to make sure that within each menu, the keyboard shortcuts for the translated messages make sense as a group (i.e. that keyboard shortcuts aren't duplicated).
• If the message to be translated contain one or more entries like {0} you must make sure that the same entries appear in your translated message. They are placeholders for text that is determined as Punt is executing, such as file names, error messages, etc.

Creating a Punt language DLL file from the PO file

Eventually we plan to setup an automated method to help organize the Punt language files. For now, you will need to arrange to get your PO file to one of the Punt project administrators, who will create the DLL file and make it available for download. Contact either dpatton or mashi on the #punt IRC channel.