Next: , Up: PO Files

2.3.1 Starting a New Translation

To start a new translation, the easiest way is to copy the existing POT as article.lang.po, where lang is your language code. For example, to prepare for a new translation of the essay http://www.gnu.org/philosophy/free-sw.html, you can simply do cd philosophy/po ; cp free-sw.pot free-sw.lang.po and then edit the latter. If free-sw.pot does not exist it is because either the article is not yet “templated” (i.e. migrated to the new style), or the GNUN maintainers have not yet added it to the value of the appropriate variable in server/gnun/gnun.mk. In that case, just ask them to do the necessary in order the POT to be generated.

You could also use the msginit utility that would populate the PO file header with the right information, provided your environment is set up correctly. See msginit Invocation.

The PO file header as generated usually looks like this: 

     # SOME DESCRIPTIVE TITLE
     # Copyright (C) YEAR Free Software Foundation, Inc.
     # 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"
     "POT-Creation-Date: 2008-02-06 16:25-0500\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: ENCODING\n"

You have to edit the header to match the already established conventions, and the rules for gnu.org translations. For reference, here is a list with all fields explained:

‘Project-Id-Version’
Add here the filename of the original article, without the sub-directory, like “banner.html” or “free-sw.html”.
‘POT-Creation-Date’
Do not edit this field, it is already set when the POT is created.
‘PO-Revision-Date’
Likewise, do not edit. This field is automatically filled in when you save the file with any decent PO editor.
‘Last-Translator’
The name and email address of the last translator who have edited the translation. Pay attention that normally this is the name of a member of your team, it can be the translation team leader if he/she was the person who updated the translation. For example: 
          Elvis Parsley <king@grassland.com>

‘Language-Team’
This field should contain the mailing list on which the translation team can be reached—sometimes this is the alias web-translators-LANG@gnu.org, but in some cases it is a separate, non-GNU list. It could be a URL of the team's homepage, provided that it contains contact details. Example: 
          French <trad-gnu@april.org>

‘MIME-Version’
Leave it like it is.
‘Content-Type’
Usually this is text/plain; charset=UTF-8; change the charset accordingly.
‘Content-Transfer-Encoding’
Set this to 8bit. Note that the PO file header ends with this field, and it should contain a newline (‘\n’). Unfortunately, some PO editors remove the newline, which causes an unnecessary revision when the file is automatically modified by GNUN's rules.

Here is an example of a properly edited header: 

     # Bulgarian translation of http://www.gnu.org/philosophy/free-sw.html
     # Copyright (C) 2008 Free Software Foundation, Inc.
     # This file is distributed under the same license as the gnu.org article.
     # Yavor Doganov <yavor@gnu.org>, 2008.
     #
     msgid ""
     msgstr ""
     "Project-Id-Version: free-sw.html\n"
     "POT-Creation-Date: 2008-02-06 16:25-0500\n"
     "PO-Revision-Date: 2008-02-09 15:23+0200\n"
     "Last-Translator: Yavor Doganov <yavor@gnu.org>\n"
     "Language-Team: Bulgarian <dict@fsa-bg.org>\n"
     "MIME-Version: 1.0\n"
     "Content-Type: text/plain; charset=UTF-8\n"
     "Content-Transfer-Encoding: 8-bit\n"

Notice the absence of the “fuzzy” marker; you should “unfuzzy” the header after entering the necessary information (this is done by simply pressing <TAB> in PO mode).

There are some special messages that appear in the POT and PO:

‘*GNUN-SLOT: TRANSLATOR'S NOTES*’
This is for translator's notes that are injected in the resulting translation. See Notes Slot, for more information. If your translation does not have notes, you must translate this as a space, that is, <SPC>.


‘*GNUN-SLOT: TRANSLATOR'S CREDITS*’
This is again optional, and should contain the name (and address) of the person who made the translation. “Translate” this string as a space (<SPC>) if you do not want your name to appear there. See Credits Slot.

Most of the PO editors do not wrap long lines that inevitably appear in msgstr's. If that happens, long lines make reading subsequent diffs harder, and are generally annoying for most people. If this issue bothers you, you can “normalize” the already finished PO translation by executing on the command line msgcat -o file.po file.po, before installing it in the repository. Either way, the build system will treat it is a valid PO file.

For those lucky Emacs users, here is a code snippet that you can put in your .emacs; doing M-x po-wrap while in PO mode will wrap all long lines: 

     (defun po-wrap ()
       "Filter current po-mode buffer through `msgcat' tool to wrap all lines."
       (interactive)
       (if (eq major-mode 'po-mode)
           (let ((tmp-file (make-temp-file "po-wrap."))
     	    (tmp-buf (generate-new-buffer "*temp*")))
     	(unwind-protect
     	    (progn
     	      (write-region (point-min) (point-max) tmp-file nil 1)
     	      (if (zerop
     		   (call-process
     		    "msgcat" nil tmp-buf t (shell-quote-argument tmp-file)))
     		  (let ((saved (point))
     			(inhibit-read-only t))
     		    (delete-region (point-min) (point-max))
     		    (insert-buffer tmp-buf)
     		    (goto-char (min saved (point-max))))
     		(with-current-buffer tmp-buf
     		  (error (buffer-string)))))
     	  (kill-buffer tmp-buf)
     	  (delete-file tmp-file)))))

It is highly desirable that you check if the PO file you finished translating (or editing) is valid, before committing it. This is done by running msgfmt -cv -o /dev/null file or by simply pressing V in PO mode. The build system automatically verifies each PO file when invoked with VALIDATE=yes, but you won't get a warm and fuzzy feeling if a stupid typo you made halts the whole update of all translations. Such things happen to everyone, so it is a good practice to check before you actually commit.