Localising GNOME Applications

As the coordinator for your team, you act as the primary contact person for the team and are responsible for organizing the other translators in your team. This includes attempting to prevent multiple translators simultaneously attempting translations of the same file.

Coordinators need to be subscribed to the gnome-i18n mailing list. This is highly recommended for all GNOME translators, but required of coordinators.

If any members of your team have CVS access, it will likely be you. If you don't, each team member will send translations to you, and you will in turn forward them to somebody with CVS access who will commit them. This ensures that all the right translations go to the right people at the right time.

Initially, at least, bugs pertaining to your translation team will come in your direction. (You're not likely to get many bugs until your translation becomes used.) Your language will have its own component in GNOME's Bugzilla bug tracking system.

The coordinator is often expected to deal with the more technical aspects of translation work, such as plural forms, updating configure.in files and generating POT files. (All of which will be covered later. We hope.)

You might also be involved in recruiting more members into your translation team. Many hands make the translations go faster, even though it might mean more work for you!

It is also your responsibility as coordinator to stop being a coordinator when it is appropriate: for example when you no longer have the time to dedicate to the effort that it deserves. If you know that you will no longer be able to perform the coordination role, ask someone to take your place in advance.

To begin with, you will need to find out what your language code is. This is a two- or three-letter code. More popular languages will tend to have two-letter codes, whereas more obscure languages will tend to get stuck with a three-letter one. For languages spoken in more than one country, a translation specific to a country will be followed by an underscore and the two-letter country code capitalized. This can further be appended with an at-sign and more qualifying information. For now, know that language codes typically look like "fr" (French) or "en_GB" (English as used in Great Britain).

If you do not know what the code for your language is, try looking around to see if there are translation efforts for other projects (such as KDE, Mozilla and OpenOffice) in your language — these will (should) use the same code. If that doesn't turn up anything, ask the mailing list for help.

GNOME uses standard codes as defined in ISO standard 639 (for language codes) and ISO standard 3166 (for country codes). The gnome-i18n members will help you identify your language code.

Your language code is used to identify your localisation, for example in the names of locales and files. Once you have your code, you can start translating.

There are a number of things that will help you immensely in your translation work.

There are different ways of translating. Some teams simple parcel out the “po file” to different people and the members work through them with a text editor and return them to the person who can commit them into GNOME. Other teams use web-based systems. All have advantages and disadvantages.

.po file details are at the end of this page as the longest section. You can jump ahead to the section on .po files if you don't intend to use anything else.

A web interface generally provides anyone with a list of strings and waits for them to suggest translations for them. Someone periodically sweeps up all the results and feeds them back into CVS. The advantage is that only the team co-ordinator and the maintainer of the web interface need to care about how to make .po files. This lets anyone who doesn't have GNOME, a useful editor, or other things help with the translation. One disadvantage is that without being able to see the rest of the file, contributors may not realise how other people are translating applications. If your team is trying to achieve consistency, this can be a problem. Another is that comments from the developer to translators explaing the string are not always shown.

Existing web interfaces include the following:

There is an excellent document available about how to checkout po/ directories, create .pot files, turn them into .po files, and check them back into CVS: Using GNOME CVS as a Translator. You must read this. It explains all the details of using the gettext tools. Since this is 90% of working with .po files, you need to know it. We have not repeated it here. We have simply added a few comments which are in addition to it. They do not replace it.

Note that you can obtain .po files from your language's status pages on the Gnome Translation Project website. (See below). Sometimes special characters (non-ASCII) can be garbled doing this, but it is a useful alternative to CVS.

A .po file is simply a list of strings from the original program, with spaces for you to put your version in. There is a set of headers at the top, some of which you will have to edit. The Project-Id-Version will become the name of the module. The POT-Creation-Date should be filled in automatically. You must edit the PO-Revision-Date yourself. Language-Team should be your team's language and ideally an email address which will contact one or more of your members. The Content-Type must be UTF-8 and you must make sure that the resulting file is in fact UTF-8 format. On UNIX and UNIX-like systems, the file command will tell you what format it is in. On a machine with all the gettext facilities installed, you can use msgfmt -cv filename.po. If the file is not UTF-8, msgfmt -cv will produce an error message saying so.

You will meet comments in the file. When they say “c-format”, this means that there are strings which the program will fill in itself. For example, the clock applet in gnome-applets has a string to translate of “%H:%M”. You can “translate” this by pasting it straight in. They will be provided by the system clock on the computer. %H is the hours. %M is the minutes.

There is a separate appendix on common C-format strings.

You will also meet messages to translators from the programmer. For example, in gnome-applets, slightly after the message quoted above you will find the comment “translators: reverse the order of these arguments if the time should come before the date on a clock in your locale”.

You will also have to replace menu accelerators: the keyboard shortcuts which can be used instead of clicking on menus. Expect contradictions and collisions in the early days. It is probably most important to do the accelerators for gtk+ first, since they will be in every single GNOME application. Then you can use the remaining letters and try to work out what combinations work the best. Don't worry if you have two or more menu options with the same accelerator. As of 2.4, GNOME will let you cycle between them.

You will often come across descriptions for GConf keys. Usually, each key has both a short and a long description. Strings which are key descriptions can be identified by the fact that they come from files with names resembling .schemas.in.h.

When translating key descriptions, be careful with sample key values, which will be enclosed in double quotes. They should not be translated. For example:

#: src/gnome-terminal.schemas.in.h:70
msgid ""
"Default color of terminal background, as a color specification (can be HTML-"
"style hex digits, or a color name such as \"red\")."
msgstr ""
"Rhagosodiad lliw cefndir y terfynell, fel penodid lliw (gall fod mewn hecs-"
"ddigidau fel yn HTML neu fel enw lliw megis \"red\")."

In the example, “red” is a sample key value, and must be copied verbatim into the translation. Note that because the double quote character is significant in .po files, it is escaped with the backslash.

If you meet English messages which you cannot understand, file a bug against the application telling the developer of the problem. If you meet English messages which you cannot reasonably translate, file a bug again. Translators as a group file dozens and dozens of these, because translators are the ones who spot them. The earlier you file these the better. When you learn what the message means, you will probably forget about filing the bug. Filing them gets them fixed, and stops other translators having to struggle with the strings.

Carlos Perelló Marín maintains status tables for each language translation in GNOME. They are available in the Gnome Translation Project pages. The tables include several views and are updated three times a day.

For each language (follow a highlighted language for details) there are tables showing the overall status and a breakdown by package. These tables contain links to the latest .pot file (if the application has not been translated at all to your language yet) or the latest .po file (if a start has been made on the translation). You can download these straight from the status pages instead of using CVS. You can't upload them that way, but the download facility is very useful.

And all of this is maintained for the final release of Gnome 1 (Gnome 1.4), the latest stable release, and for the packages which will become the next stable release. At the time of writing (January 2004), 2.4 was the last stable release and the 2.5 release, which will become 2.6, is under development.

As soon as translations for your language have been committed to CVS, your language will acquire its own section in the status tables. You should probably bookmark the pages relevant to your language. They are very very useful.

Your language page will have a URL of the form http://developer.gnome.org/projects/gtp/status/gnome-2.6/XX/index.html where XX should be replaced by your language code (lower-case). The above URL is for the releases that will become GNOME 2.6. If you want to see the stable release of Gnome, adjust the URL accordingly.

You will generally discover changes when you update your copy of a module in Gnome CVS or when you refresh your browser on your status pages. Again, How to use GNOME cvs as a translator is your guide to the necessary cvs commands. If you know there are more strings to translate, then you need to generate a new .pot file which contains all the strings to translate and then to merge it with your xx.po file which has a less up-to-date set of translated strings. Generate the .pot file with intltool-update --pot. Merge the two together with msgmerge -o new-xx.po xx.po .pot and try very hard to get those in the right order!

FIXME: mention intltool-update xx

Then run msgfmt -cv new-xx.po to see how much work remains. If you are lucky, there will be many many “fuzzy” strings: strings which are so similar to already-translated messages that the msgfmt program has suggested that you use the old translation for the new string.

Go through your new file searching for instances of the string “fuzzy”. If it is in a comment above a translation that looks correct, then remove the word “fuzzy”. If “fuzzy” is the only word on the line, you can safely remove the whole comment. If you do not remove the word “fuzzy” then the translation will not be used. For example:

#, fuzzy
msgid "Blah blah blah."
msgfmt "La la la."

In this case, if you are confident in the translaton, the line with "fuzzy" in it can be removed entirely:

msgid "Blah blah blah."
msgfmt "La la la."

However, you may come across a something like this:

#, c-format, fuzzy
msgid "Very important: %s"
msgstr "Pwysig iawn: %s"

In this case, if you wish to remove the fuzziness, the "c-format" tag must be left intact:

#, c-format
msgid "Very important: %s"
msgstr "Pwysig iawn: %s"

Sometimes a whole set of messages are moved to a new module. This can be particularly disheartening if you had translated them once already and think you now have to do them again. You can save on the work by using the .po file from that module with msgmerge. You can also generate yourself a compendium of messages you have translated which you can keep, edit, and use as a source of suggested translations. You can do this using msgcat, in the form msgcat a.po b.po c.po > compendium. You should check the contents of the compendium before using it for translation, especially for strings of the form “#-#-#-#-#” which indicate conflicts among the original .po files. This feature also means that you can use msgcat to check for inconsistencies among .po files. Once you have created your compendium with msgcat, you can make use of it with msgfmt, as you would any other .po file.

You may find that a whole selection of messages are no longer used in the application. They will be moved down to the bottom of the .po file and left there, commented-out. A # at the start of a line comments it out. It is ignored. Unless there is a very large number of these and they really are getting in the way, do not delete these lines. They may come back into the application. They can also be used by the msgmerge program as a source for finding fuzzy translations. Leave them where they are.