Correct management of .po files for translation

["Daniel P. Berrange" <berrange@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 3211 bytes --]

In updating Fedora rawhide to work against xen-unstable.hg (3.0.5) I noticed
that there is now gettext support for translating the error messages returned
from XenAPI in xm. Unfortauntely the way the .po files have been created is
completely wrong & useless for translators to work kwith.

First there is no master .pot file - merely an english 'translation'. Since
the convention is for the untranslated strings to be in english to start with,
providing an english .po  file is redundant unless you specialize it to a
variant like  en_GB.po

The core problem though is that the catalog file ..

tools/python/xen/xm/messages/en/xen-xm.po

..does not contain untranslated strings at all - it is instead full of symbolic
constants.

  msgid "INTERNAL_ERROR"
  msgstr "Internal error: %(1)s."

  msgid "MAP_DUPLICATE_KEY"
  msgstr "This map already contains %(1)s -> %(2)s."

  msgid "MESSAGE_METHOD_UNKNOWN"
  msgstr "The method %(1)s is unsupported."

  msgid "MESSAGE_PARAMETER_COUNT_MISMATCH"
  msgstr "The method %(1)s takes %(2)s argument(s) (%(3)s given)."

There are two critical reasons why msgid should always contain the master
english untranslated string:

  - Translators need to be able to compare the original english alongside
    the translated text to ensure accurate translations. Referring to external
    files to find the english is not practical

  - The msgmerge tool used to periodically update the catelogs looks at
    the msgid entries to identify added / removed / editted strings. If
    the msgid is a symbolic constant it'll never be able to identify strings
    which have changed & thus mark them as needing re-translation

Basically the code is abusing the gettext translation service to do both the
constant -> string conversion & the translation in one go. The normal way to
do the constant -> string conversion is to have a statically declared hash
table in the application itself. This contains the master english strings
annotated with  N_(...string..).  The xgettext program will then generate
the .pot files automatically in the correct format.

I'm attaching an example to show how this ought to work in the Xen case.
The makefiles could be hooked up to automatically run

  xgettext --keyword=N_ -o xen-xm.pot tools/python/xen/xm/XenAPI.py

Which generates a sensible catalog file looking like

  #: tools/python/xen/xm/XenAPI.py:58
  #, python-format
  msgid "Internal error: %(1)s."
  msgstr ""

  #: tools/python/xen/xm/XenAPI.py:59
  #, python-format
  msgid "This map already contains %(1)s -> %(2)s."
  msgstr ""

  #: tools/python/xen/xm/XenAPI.py:60
  #, python-format
  msgid "The method %(1)s is unsupported."
  msgstr ""

For each new language the translators simply do xen-xm.pot to  fr_FR.po, and 
fill in the msgstr field. When xen-xm.pot is later updated, the translations
can in turn be updated using  msgmerge, etc, etc


Regards,
Dan.
-- 
|=- Red Hat, Engineering, Emerging Technologies, Boston.  +1 978 392 2496 -=|
|=-           Perl modules: http://search.cpan.org/~danberr/              -=|
|=-               Projects: http://freshmeat.net/~danielpb/               -=|
|=-  GnuPG: 7D3B9505   F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505  -=| 

[-- Attachment #2: xen-gettext.patch --]
[-- Type: text/plain, Size: 1609 bytes --]

diff -r 2d25db73ddc1 tools/python/xen/xm/XenAPI.py
--- a/tools/python/xen/xm/XenAPI.py	Wed Apr 04 10:42:58 2007 +0100
+++ b/tools/python/xen/xm/XenAPI.py	Wed Apr 04 11:36:58 2007 -0400
@@ -49,6 +49,22 @@ import xmlrpclib
 
 import xen.util.xmlrpcclient as xmlrpcclient
 
+def gettext_noop(str):
+    return str
+
+N_ = gettext_noop
+
+errormap = {
+    "INTERNAL_ERROR": N_("Internal error: %(1)s."),
+    "MAP_DUPLICATE_KEY": N_("This map already contains %(1)s -> %(2)s."),
+    "MESSAGE_METHOD_UNKNOWN": N_("The method %(1)s is unsupported."),
+    "MESSAGE_PARAMETER_COUNT_MISMATCH": N_("The method %(1)s takes %(2)s argument(s) (%(3)s given)."),
+    "SESSION_AUTHENTICATION_FAILED": N_("Permission denied."),
+    "VALUE_NOT_SUPPORTED": N_("Value \"%(2)s\" for %(1)s is not supported by this server.  The server said \"%(3)s\"."),
+    "HANDLE_INVALID": N_("The %(1)s handle %(2)s is invalid."),
+    "OPERATION_NOT_ALLOWED": N_("You attempted an operation that was not allowed."),
+    "NETWORK_ALREADY_CONNECTED": N_("The network you specified already has a PIF attached to it, and so another one may not be attached."),
+    }
 
 translation = gettext.translation('xen-xm', fallback = True)
 
@@ -68,7 +84,7 @@ class Failure(Exception):
 
     def __str__(self):
         try:
-            return translation.ugettext(self.details[0]) % self._details_map()
+            return translation.ugettext(errormap[self.details[0]]) % self._details_map()
         except TypeError, exn:
             return "Message database broken: %s.\nXen-API failure: %s" % \
                    (exn, str(self.details))

[-- Attachment #3: Type: text/plain, Size: 138 bytes --]

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel