[Dev] [README] i18n checkin

[Brian Kirsch]

Aloha,
I just checked in a significant update to i18n in Chandler (rev 7213).
On your next svn update you will need to recreate your repository.

This is a bulk commit encompassing many i18n improvements. A few of the 
highlights include:
================================================

1. The displayName attribute is now schema.Text which means it only 
accepts unicode values :)

2. If Chandler is started with the --locale test. All translatable 
strings will have a surrogate pair character inserted at the beginning. 
This is useful for testing and to verify UI strings are wrapped in _(). 
The 'Generate Data'  menu items with the 'test' locale inserts non-ascii 
characters to items on a semi-random basis. Again, this is great for 
testing.

3. Added a __unicode__ method to the ContentItem base class.

4. Changed all translatable strings to use dicts for the keys. It is 
very hard for a translator to get the context of a translation when it 
is something like this "Test results (%s) failed for %s". It is much 
better to have "Test results (%(accountType)s )failed for %(user)s". To 
use the dict one would do this:

 >>> from i18n import OSAFMessageFactory as _
 >>> s = _(u"Test results %(accountType)s failed for %(user)s") % 
{'accountType': "IMAP", 'user': "Brian Kirsch"}
 >>> print s.encode('utf8')
 >>> #Assuming the locale is set to English
 >>> u'Test results (IMAP) failed for Brian Kirsch'

5. Created the tools/createPot.py file which will produce the 
chandler.pot translation file for all _() in application, parcels, 
crypto, and i18n. The chandler.pot file will be created for now in the 
$CHANDLERHOME/chandler directory.

 From the command line:

%) cd $CHANDLERHOME/chandler
%) ./release/RunPython tools/createPot.py


6. Created the osaf.messages file which contains common translation 
strings leveraged through out the Chandler source.
 >>> from osaf import messages
 >>> print messages.ME.encode('utf8')
 >>> #Assuming the locale is set to English
 >>> u'me'

7. Created the ChandlerException which unlike the base Exception class 
handles unicode error messages. This is useful because right now many 
parts of Chandler capture exceptions and display them in the UI. If the 
exception comes from outside of Chandler  however it must be translated 
manually before display.


 >>> from osaf import ChandlerException
 >>> raise ChandlerException(_(u"This is a localized error message"))

7. Random i18n improvements to the source code such as removing 
translation methods around strings which were not displaying in the UI 
and adding translation methods to strings which were displaying in the UI.

8. Fixed some bugs I found in the Chandler code related to i18n and 
exception handling

9. Identified areas of Chandler which are not correctly dealing with 
i18n issues. I will be filing bug reports today but for the most part 
Chandler components are handling i18n very well :)


So what should I do you ask?
======================
1. Please only check in translatable string with dict look ups. No more 
%s in translations. Feel free to %s for non-displayable tasks such as 
writing messages to the log.

2. Please create translation sentences not sentence fragments. For 
example _(u"ago") does not give enough context for a translator to work 
with. The translation of 'ago' will depend on the way it is used in a 
sentence. Also where 'ago' appears in a sentence will change from 
language to language.

2. Please Please Please run Chandler with --locale test before you check 
in a major change. Look for the following:

    a. Did I add any strings to the UI? Are they wrapped in _() for 
translation?
    b. When I do a 'Generate Data' from the Test menu does my module 
work properly? For example, can I share items with non-ascii values 
properly, do they import and export as Ical events, can I send them in 
an email?

3. Use osaf.messages for common translations strings such as 'All' and 
'Account Preferences' instead of redefining them in code.

4. Do not use displayNames as keys for lookup. Displaynames can change 
depending on the locale and are not the appropriate place to do 
comparisons. For example, some parts of the UI were checking if the name 
of the collection is 'All'. Well this will fail in another locale. 
Thanks to John for looking through the CPIA code and removing the 
displayName collection lookups.

5. Only put _() a translation method around strings that are actually 
displayed to the user in the UI. This reduces the burden on the translator.


There will be a 'Busy Developers Guide' for internationalization coming 
shortly.

Thanks,
Brian

-- 
Brian Kirsch - Email Framework Engineer
Open Source Applications Foundation
543 Howard St. 5th Floor
San Francisco, CA 94105
(415) 946-3056
http://www.osafoundation.org