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.