[Dev] [README] i18n checkin

[Brian Kirsch]

Thanks Alec for the feedback!
One additional comment: Although there may be a few random cases where 
we need to define date format information in the translation like Alec's 
example below 99% of this formatting should come from PyICU via its 
format classes (DateFormat, NumberFormat, etc). PyICU maintains this 
information for 230+ locales.


-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



Alec Flett wrote:

> This is great work, thanks for going and doing all the legwork on this.
>
> There was a case in CalendarCanvas that I think is very subtle that I 
> wanted to bring to everyone's attention, because you may run into a 
> case of this without realizing it.The simple lesson here is that 
> symbols also need to be translated.
>
> Here's the subtle case: the calendar canvas displays the month and 
> year at the top of the calendar, and when a week spans 2 months, it 
> shows both months plus the year. The code for the 2nd case looked like 
> this:
>
> "%s - %s %d" % (month1, month2, year)
>
> It might look like the format string is not necessary to translate 
> because there are no words, but you still need a locale-specific 
> string here. In some language, you might display the year first, then 
> the two months. Or, the character '-' might not mean "to" in your 
> language and you may need another character or word.
>
> the proper way of making a translatable string is using the python 
> keyword syntax that Brian has gone through and fixed most everywhere:
>
> _(u'%(month1) - %(month2) %(year)d') % { month1: month1, month2: 
> month2, year: year}
>
> So for instance in spanish, the format string might be '%(year)d 
> %(month1)s a %(month2)s'
>
>
> Alec
>
> Brian Kirsch wrote:
>
>> 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
>>
>