[z3-checkins] r14403 - z3/Five/trunk/doc

[philikon at codespeak.net]

Author: philikon
Date: Thu Jul  7 19:59:16 2005
New Revision: 14403

Added:
   z3/Five/trunk/doc/i18n.txt   (contents, props changed)
Log:
added i18n documentation based on my email to the five list
(http://thread.gmane.org/gmane.comp.web.zope.z3base.five/581)


Added: z3/Five/trunk/doc/i18n.txt
==============================================================================
--- (empty file)
+++ z3/Five/trunk/doc/i18n.txt	Thu Jul  7 19:59:16 2005
@@ -0,0 +1,76 @@
+Internationalization
+====================
+
+Translation
+-----------
+
+Five registers its own translation service mockup with the Page
+Templates machinery and prevents any other product from also doing so.
+That means, Five always assumes control over ZPT i18n.  When a certain
+domain has not been registered the Zope 3 way, Five's translation
+service will see that the utility lookup fails and use the next
+available fallback translation service.  In case of no other
+translation service installed, that is just a dummy fallback.  In case
+you have Localizer and PTS installed, it falls back to that.
+
+To register Zope 3 style translation domains, use the following ZCML
+statement::
+
+  <i18n:registerTranslations directory="locales" />
+
+where the 'i18n' prefix is bound to the
+http://namespaces.zope.org/i18n namespace identifier.  The directory
+(in this case 'locales') should conform to the `standard gettext
+locale directory layout`__.
+
+.. __: http://www.gnu.org/software/gettext/manual/html_chapter/gettext_10.html#SEC148
+
+
+Preferred languages and negotiation
+-----------------------------------
+
+Fallback translation services such as PTS and Localizer have their own
+way of determining the user-preferred languages and negotiating that
+with the available languages in the respective domain.  Zope 3
+translation domains typically adapt the request to
+IUserPreferredLanguages to get a list of preferred languages; then
+they use the INegotiator utility to negotiate between the preferred
+and available languages.
+
+The goal of the sprint was to allow both fallback translation services
+(PTS, Localizer) and Zope 3 translation domains come to the same
+conclusion regarding which language should be chosen.  The use case is
+that you have a site running Localizer or PTS and a bunch of "old"
+products using either one of those for translation.  Now you have an
+additional, "new" Five-based product using Zope 3 translation domains.
+Most of the time, a page contains user messages from more than one
+domain, so you would all domains be translated to the same language.
+
+
+Adjusting behaviour to your environment
+---------------------------------------
+
+The default behaviour for choosing languages in Five is the one of
+Zope 3: analyze the Accept-Language HTTP header and nothing more.  In
+addition, Five providees ``IUserPreferredLanguages`` adapters for
+Localizer and PTS that choose languages the exact same way Localizer
+or PTS would.  So, if you're using Five in a Localizer-environment,
+you need this in your product's ``overrides.zcml``:
+
+    <adapter
+        for="zope.publisher.interfaces.http.IHTTPRequest"
+        provides="zope.i18n.interfaces.IUserPreferredLanguages"
+        factory="Products.Five.i18n.LocalizerLanguages"
+        />
+
+If you're using PTS:
+
+    <adapter
+        for="zope.publisher.interfaces.http.IHTTPRequest"
+        provides="zope.i18n.interfaces.IUserPreferredLanguages"
+        factory="Products.Five.i18n.PTSLanguages"
+        />
+
+That way Zope 3 translation domains will always come to the same
+conclusion regarding the language as your original translation service
+would.