= Django Internationalization =

''See also: [wiki:Localization Localization], Ticket #65, [http://developers.sun.com/dev/gadc/i18ntesting/checklists/allquestions/allquestions.html Sun.com i18n checklist index]''

There are a lot of things we need to do to get Django properly internationalised.

This page and subject are actively '''under discussion''' over on [http://groups-beta.google.com/group/django-developers/browse_thread/thread/6a222dcb4b3978b8/a93afb70fb8a3f80 this thread in django-developers].

There are two parts to Django i18n, that need to be treated separately: Program Internals, and Templating system. This page is an attempt to create an overview of what needs to be done, in order to generate discussion. Eventually, some more tickets will be created out of these steps.

== Program Internals ==

This is not an exhaustive list, we need to identify more things to do, and go into more detail.

Draft proposition is in [http://groups-beta.google.com/group/django-developers/msg/0ddfffa4b6472d1c this message]

=== New Code ===
The [http://www.python.org/doc/current/lib/module-gettext.html gettext] module seems an ideal place to start, but both the gettext module and it's sibling, the [http://www.python.org/doc/current/lib/module-locale.html locale] module, seem to only really work well for single-threaded, single-locale applications. Since part of the i18n effort is to try to enable working with multiple-language websites, it seems that we must unfortunately create a lot more of the i18n framework than we would otherwise have thought. The two modules are not a total loss, we can still use large amounts of them as long as we can specify the locale on-the-fly, they are just not perfect for our need. See [http://groups-beta.google.com/group/django-developers/msg/a93afb70fb8a3f80 this message for problems with gettext] and [http://groups-beta.google.com/group/django-developers/msg/04ee6e2311b09b9b this message for problems with locale] and subsequent discussions on the thread.

 * Create our own string type which will do translations lazily on an as-required basis. Will need to cope with slicing, and locale-specific interpolation of numbers, dates, etc. See [wiki:I18nString I18nString] for a more detailed specification.
 * Work out how to set locale to be per-session, with appropriate fallbacks.
 * Locale negotiatation: HTTP Defines an {{{Accept-Language}}} header (see section 14.4 of the [http://www.faqs.org/rfcs/rfc2616.html HTTP RFC]), a Django app should by default send out content in the preferred language of the browser, or if that is not available, work down the list of acceptable languages, trying to find one until giving up and falling back on the default language.
    * In any case, a user-set locale should override any negotiated locale. If I'm in a Turkish internet café, the page should come up in Turkish until I click on English, at which point I should continue in English.

=== Current Code that needs modifying ===

 * Identify all strings in all modules that need internationalising. I suggest one ticket per major module group, e.g. core, meta, templatetags.
    * This includes all error messages. If exceptions with error messages are passed on to the user (e.g. Database errors), these need to be intercepted and translated appropriately, even if it's just adding something like "A Database Error Occurred: " before printing out the traceback or message.
 * Recode meta.*Field to print out the translated field name even if no field name was specified
    * This probably means coding up some sort of .pot file generator in django-admin.py or similar utility that understands things like meta.*Field models having a default name when none is specified.
 * Ensure things like date select boxes in the admin interface show locale-specific month names.
 * Ensure that all code can cope with unicode strings. Specifically, remove all references to {{{str()}}} and any string interpolation using non-unicode strings for anything other than essential data that needs keeping as strings, e.g. module names.

== Templating System ==

This is, potentially, the easier of the two.

 * Define a common locale directory format - something like application/localecode/template.html eg: {{{poll/en/template.html}}} or something like application/template.html.localecode eg: {{{poll/template.html.en}}}
 * Modify generic views to cope with locale template searching, both explicitly passed on locales (for websites that want to have {{{http://example.com/en/2005/08/03/}}} or {{{http://example.com/2005/08/03/en}}} and implicit locales in things like sessions.
 * Possibly: Create a generic i18n view, which copes with people sticking locale codes in URLs eg: {{{http://example.com/myapp/en/mypage/}}} or {{{http://example.com/myapp/mypage/en/}}}
 * Put locales into the Templating system. Specifically, a locale object needs to be available in all templates for things like making up URLs, and displaying the current locale on the page, and also {{{{% extends %}}}} needs to be made (optionally) locale-aware.
 * Find an easy way to mark template string for internationalization, and get the template system to deal with this appropriately (or just specify that each language should use its own set of templates, though this can be a big drag if you have 40 languages' worth of templates you want to make a minor change in.)
 * Fully internationalize things like the date filter, to make sure it prints out locale-specific month names.

== Miscellanea, and items for further discussion ==

 * How does Plone do it? They claim to be "fully internationalized". They have documentation on how to [http://plone.org/documentation/how-to/i18n-for-developers/ internationalize page templates] but I can't find anything for internal strings and objects. (When I investigated Plone, there seemed to be no easy single-click wayof changing language without going through Tools-Settings-etc which was quite annoying, as the translation to my preferred language was very poor)
 * Write documentation on how to do all this stuff, for the programmer. (I'm quite happy to do this -- [wiki:Moof Moof])

== i18n in Zope ==

They have extracted the locale data from the [http://www-306.ibm.com/software/globalization/icu/ ICU project], and made several classes that deal with all(?) aspects of i18n/l10n, see:

 * http://www.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/Zope3Book/i18noverview.html
 * http://svn.zope.org/Zope3/trunk/src/zope/i18n/
 * http://svn.zope.org/Zope3/trunk/src/zope/i18n/locales/data/pt_PT.xml?view=auto (example pt_PT locale data)
   
Another possibility, is to use [http://pyicu.osafoundation.org/ PyICU]; this library wraps the ICU library in a python module.

== i18n in another Python web applications ==

 * Mailman: http://barry.warsaw.us/papers/mailman-freenix-2003/node8.html ([http://cvs.sourceforge.net/viewcvs.py/mailman/mailman/Mailman/i18n.py?rev=2.10.2.2&view=markup source])
 * Roundup: http://roundup.sourceforge.net/doc-0.8/developers.html#internationalization-notes ([http://cvs.sourceforge.net/viewcvs.py/roundup/roundup/roundup/i18n.py?rev=1.14.2.1&view=markup source])
 * itools: http://www.ikaaro.org/itools