UPGRADE.txt

***************************************************************************
Localizer 0.8.1
***************************************************************************

  * The request variable USER_PREF_LANGUAGES isn't a list anymore,
    now it's an object that represents a tree. Any code that directly
    reads or modifies USER_PREF_LANGUAGES will be broken. Tell me
    if you did it.

  * The Localizer class provides a feature known as "locale folders"
    that lets to manage any kind of multilingual content. Now this
    feature is deprecated. A new class named "LocalFolder" provides
    a better solution for this, please move to it as soon as posible,
    in the next release the deprecated feature will be removed!!

    The quickest way to move from "Localizer" to "LocalFolder" is:

      0. Do a backup of the database;

      1. Create in the root of your web site a "LocalFolder" instance called,
         for example, "locale";

      2. Go to the management screens of "locale" and create an attribute
         named, for example, "folder";

      3. Add as many languages as needed in the tab "Languages";

      4. Create a folder for every language in the "Contents" tab, for
         example, "folder_en", "folder_es", etc..;

      5. For each language copy all the stuff from the Localizer instance
         to "locale". For example, copy everything in "Localizer/es" to
         "locale/folder_es";

      6. Now the most time expensive step, go to all the templates and scripts
         that refer to any object in the "Localizer" instance and change to
         use "locale" instead.

         For example, if you had an image named "logo" and you called it with:

           <dtml-var logo>

         change it to:

           <dtml-with locale><dtml-var logo></dtml-with>

         or to:

           <dtml-var "locale.logo()">

         Hopefully you will have to modify few methods;

      7. And finally, remove the "Localizer" instance!!

  * The previous way to internationalize Python code from Python
    products has been deprecated. Read the documentation to know
    how it should be done from now on. However, the deprecated
    way will be preserved for a while, probably a long while.


***************************************************************************
Localizer 0.8.0
***************************************************************************

  * The 0.7 version saw a big redesign of message catalogs, and
    also of the way they're used. Before they were implicitly called,
    through a globaly available "gettext" method, this feature
    was implemented in the "Localizer" class.

    In the 0.7 version message catalogs became an independent class,
    its instances are explicitly called. The old way to use message
    catalogs was preserved for backwards compatibility.

    Now, in version 0.8, the old way to use message catalogs (through
    the global "gettext" method) has been removed. To upgrade to this
    version follow the steps:

      0. If you upgrade from a version previous to 0.7 upgrade first
         to 0.7.x

      1. Move all your 'MessageCatalog' instances with the id
         'Messages' that are inside of a 'Localizer' instance
         to the same level in the hierarchy where is the
         'Localizer' object, but with the name 'gettext'.

         For example if you have "/a/b/c/Localizer/Messages" you
         should move the 'Messages' object to "/a/b/c/gettext".

         [!] This will work in most situations, you only could get
             wrong behaviour if you're using Localizer instances
             inside other Localizer instances. For example if you
             have the objects "/a/b/c/Localizer/Messages" and
             "/a/b/c/d/Localizer/Messages".

             I guess very few people, if any, will have a configuration
             like this one, so I don't provide any upgrade path. If
             you've something like this send me an email before doing
             anything.

      2. Don't do anything for a few days, just to be sure that
         everything works.

      3. Upgrade to the 0.8 version.

    Don't hesitate to contact me if you have any problem or doubt.



***************************************************************************
Localizer 0.7.0
***************************************************************************

  * There're several changes that require all Localizer instances
    to be upgraded, to do so go to the management interfaces of
    each Localizer instance and click the "upgrade" button that
    will appear.

    Be careful, the upgrading must be done with access rules
    deactivated, for example: "www.foo.com/bar/Z/manage"

  * LocalContent instances and other instances of classes that
    inherit from LocalPropertyManager also need to be upgraded.
    To do it just run the same script used to upgrade to the
    0.6 version, it is:

       obs = context.ZopeFind(context, None, None, None,
                              'isLocalPropertyManager == 1',
                              None, None, None, None, 1)

       for path, ob in obs:
           ob.manage_upgrade()

       return '%d objects upgraded' % len(obs)

  * There're several changes in the API that could break your
    code if you have used directly the Localizer API, if in
    doubt send me an email.


***************************************************************************
Localizer 0.6.1
***************************************************************************

  Before 0.6.0 changeLanguageForm was a LocalDTMLFile, in 0.6.0
  I changed it to a DTML Method. Now it's again a LocalDTMLFile.

  To upgrade go to each Localizer instance and remove the
  changeLanguageForm method. If you don't do it nothing will
  break, but anyway it's encouraged.

  If you're curious about this change, it's because I've finally
  discovered which is the difference between DTMLFile and HTMLFile:
  bindings can be used from a DTMLFile.


***************************************************************************
Localizer 0.6
***************************************************************************

 * LocalContent and LocalPropertyManager      

   All LocalContent objects and instances of classes that inherit
   from LocalPropertyManager need to be upgraded.

   Create and run a Python script in the root with the code:

       obs = context.ZopeFind(context, None, None, None,
                              'isLocalPropertyManager == 1',
                              None, None, None, None, 1)

       for path, ob in obs:
           ob.manage_upgrade()

       return '%d objects upgraded' % len(obs)

 * All Localizer instances also need to be upgraded, but it's done
   automatically. To verify it:

    - test that the 'hook_traversal' property has been removed.

    - test that the Localizer has a DTML Method called changeLanguageForm.

   Some future release, probably 0.7, will be incompatible with
   versions < 0.6. So it won't be possible, for example, to upgrade
   from 0.5.1 to 0.7 directly; it must be from 0.5.1 to 0.6.x to 0.7.

   In short: upgrade to 0.6 as soon as posible!!

 * Other minor changes:

    - Now get_available_languages returns a list of tuples of two
      elements: [(id, title), ..]

      For example, [('en', 'English'), ('es', 'Spanish'), ...]

    - Now the title of local folders is not used in changeLanguageForm.

    Perhaps there're other minor changes that could break something.


***************************************************************************
Localizer 0.3
***************************************************************************

In Localizer versions < 0.3 the way to localize DTML files was:

  from Products.Localizer.LocalizedDTMLFile import LocalizedDTMLFile
  xxx = LocalizedDTMLFile('xxx', globals())

Since version 0.3 the right way to do it is:

  from Products.Localizer import LocalDTMLFile
  xxx = LocalDTMLFile('xxx', globals())

In 0.3 version the old way was still supported, but deprecated. Since
version 0.4 the old way is no longer available, so products using it
will break.