Some hints and guidelines for the .po file headers

[Christian Rose <menthos gnome org>]

I noticed we don't have any really good guidelines on what the .po file
header should look like and contain. Also, I noticed that while many
teams follow a similar style, some teams diverge also very much diverge
from it, both with a different style and sometimes lacking important
information.

Gettext provides a very useful template when it generates an empty pot
file:

        # SOME DESCRIPTIVE TITLE.
        # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
        # This file is distributed under the same license as the PACKAGE package.
        # FIRST AUTHOR <EMAIL ADDRESS>, YEAR.
        #
        #, fuzzy
        msgid ""
        msgstr ""
        "Project-Id-Version: PACKAGE VERSION\n"
        "Report-Msgid-Bugs-To: \n"
        "POT-Creation-Date: 2004-07-21 05:06+0200\n"
        "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
        "Last-Translator: FULL NAME <EMAIL ADDRESS>\n"
        "Language-Team: LANGUAGE <LL li org>\n"
        "MIME-Version: 1.0\n"
        "Content-Type: text/plain; charset=CHARSET\n"
        "Content-Transfer-Encoding: 8bit\n"
        "Plural-Forms: PLURALEXPRESSION\n"

Basically, all fields written in UPPERCASE in this template should be
filled in.
In addition, it's very important to remove the "#, fuzzy" line when
you're done with the header. If you don't do so, gettext will generate
warnings.


Let's go through the sections in the header one by one:

	# SOME DESCRIPTIVE TITLE.

Here it's recommended to write something that describes the file, for
example "German translation of Nautilus." or "Swedish messages for
Evolution" or something like that.



	# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER

The "YEAR" needs to be replaced by the current year, like "2004". If
there is already an older year here (like "2002"), then add the current
year behind it in a comma-seperated list: "2002, 2004". Don't use
intervals, try to list each year seperately.

What the "THE PACKAGE'S COPYRIGHT HOLDER" should be replaced with is the
subject of different interpretations. In any case, it should be assigned
to someone (don't leave the default filled in!), and most seem to prefer
assigning it to "Free Software Foundation, Inc." or "GNOME Foundation".

Don't assign the copyright to yourself, your employer or some other
entity that you aren't sure would always try and have the resources to
defend your contribution legally.



	# This file is distributed under the same license as the PACKAGE package.

Just replace "PACKAGE" with the software name here, like "evolution" for
Evolution.



	# FIRST AUTHOR <EMAIL ADDRESS>, YEAR.

Here you should list all people that have contributed to the translation
individually, one on each line, with their personal mail addresses and
what years they did contribute. If Bob Smith originally worked on the
translation in 1998, and there was noone who updated it until Anne Jones
updated it first in 2000 and then 2002 and every year since, the list
should look like this:

	# Bob Smith <bob bobsmith org>, 1998.
	# Anne Jones <annej yahoo com>, 2000, 2002, 2003, 2004.



	# 

Here you can add your own comments about the file, i.e. special
terminology to watch out for, etc. A useful thing IMO is to include the
special CVS keyword $Id$ here. This will get expanded when committed to
a line that describes who last committed the file and when. I.e. if I
enter this:

	# $Id$

then it will become

	# $Id: sv.po,v 1.21 2004/07/21 21:05:42 menthos Exp $

when I commit the file, and I can look at this later to tell when the
file was last committed.



	#, fuzzy

This line in the header needs to be removed for your po file to work
properly. It's there so you remember to edit the po file header. :-)



	"Project-Id-Version: PACKAGE VERSION\n"

Replace "PACKAGE VERSION" by something short that uniquely identifies
this particular translation, for example "evolution HEAD" or just
"evolution".



	"Report-Msgid-Bugs-To: \n"

This should, when it works, be filled in by gettext itself, describing
where to report problems with the messages. You don't need to fill in
anything yourself here.



	"POT-Creation-Date: 2004-07-15 05:06+0200\n"

This should be filled in by gettext itself, describing when the po file
was last regenerated from the sources. You don't need to fill in
anything yourself here.



        "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"

Here you should fill in the date (ISO style), time and numerical
timezone of the time you last edited the file. I.e. if I last edited the
file at 2 minutes past nine p.m. the 21st of July 2004 in the time zone
of Sweden during daylight savings' time, I should enter

	"PO-Revision-Date: 2004-07-21 21:02+0200\n"

You can get the current date correctly formatted by entering the
following in a GNU/Linux console: 

	$ date +"%Y-%m-%d %H:%M%z"



        "Last-Translator: FULL NAME <EMAIL ADDRESS>\n"

Here you should enter the last translator who edited the file and this
person's email address.



        "Language-Team: LANGUAGE <LL li org>\n"

Here you should enter the name of your team, and an email address where
the team can be reached.



        "MIME-Version: 1.0\n"

This doesn't need to be changed.



        "Content-Type: text/plain; charset=CHARSET\n"

"CHARSET" needs to be replaced by "UTF-8" for GNOME translations. Also
remember to check that the file is indeed valid UTF-8!



        "Content-Transfer-Encoding: 8bit\n"
        
This doesn't need to be changed.



        "Plural-Forms: PLURALEXPRESSION\n"

This line needs to be added in case the software uses ngettext. The
correct contents of this line depends on the affected language. If
you're unsure what you should fill in here, ask.



Finally, here's an example of what a po file header can look like:

        # Swedish messages for nautilus.
        # Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
        # Andreas Hyden <a hyden cyberpoint se>, 2000.
        # Richard Hult <rhult hem passagen se>, 2000.
        # Christian Rose <menthos menthos com>, 2000, 2001, 2002, 2003, 2004.
        # Martin Norbäck <d95mback dtek chalmers se>, 2000, 2001.
        #
        # $Id: sv.po,v 1.284 2004/07/14 19:33:38 menthos Exp $
        #
        # "folder" ska översättas med "mapp"
        # ("folder" should be translated with "mapp")
        #
        msgid ""
        msgstr ""
        "Project-Id-Version: nautilus\n"
        "Report-Msgid-Bugs-To: \n"
        "POT-Creation-Date: 2004-07-14 21:30+0200\n"
        "PO-Revision-Date: 2004-07-14 21:32+0200\n"
        "Last-Translator: Christian Rose <menthos menthos com>\n"
        "Language-Team: Swedish <sv li org>\n"
        "MIME-Version: 1.0\n"
        "Content-Type: text/plain; charset=UTF-8\n"
        "Content-Transfer-Encoding: 8bit\n"
        "Plural-Forms: nplurals=2; plural=(n != 1);\n"


I hope some people find this useful. Perhaps something on po headers
could be added to http://developer.gnome.org/projects/gtp/l10n-guide/.


Christian