small addition to i18n.txt with regard to caching

[hugo]

The i18n.txt (reading much smoother than my version!) should point out that the LocaleMiddleware needs to be _after_ the CacheMiddleware (if used), because it modifies the Vary-header. Otherwise the accept-language header wouldn't be used correctly.

And it is a case for #730: the LocaleMiddleware needs in process_request access to the session, so must come _after_ SessionMiddleware. But SessionMiddleware and LocaleMiddleware must come _after_ CacheMiddleware, so that the caching sees the Vary header in process_response (due to the reversed order of middleare). That's exactly the kind of "order deadlock" the user can't solve without giving explicit middleware order.

I copied the above text to #730, too.

[hugo]

Another correction: I left in a hint that LocaleMiddleware is required for application translation files. That's not the case any more, the files are all pulled in on first access to a language. The system before worked by using fallback languages down the chain of locations as described in the document, but now works by "working up" from the base and merging. It loads a base translation file from django, then loads the given LOCALE_PATHS translation file, merges it in (overwriting identical message ids). Then it loads the project message file and then all app message files in the order of INSTALLED_APPS. And that's done even without the LocaleMiddleware

Before it only pulled in the explicit application translation file that was bound to the application the view was in, but that was too fragile and problematic, because there are lot's of places where there isn't an application - if for example the view function is outside any application directory. So I had to drop the application-specific translation handling and just lump all together in one big translation object. It's faster the way it is now, so it's not that bad - we only lose the possibility to translate one string differently per application, as everything internally is one big dict of message IDs.

[Adrian Holovaty]

In [1117] -- Added note about CacheMiddleware to docs/i18n.txt.

[Adrian Holovaty]

Hugo -- I'm not sure I understand your comment (the first comment to this ticket). How do the docs need to change?

[anonymous]

Index: i18n.txt                writing-apps-guide-outline.txt
===================================================================
--- i18n.txt    (revision 1092)
+++ i18n.txt    (working copy)
@@ -393,6 +393,9 @@
     * Make sure it's one of the first middlewares installed.
     * It should come after ``SessionMiddleware``, because ``LocaleMiddleware``
       makes use of session data.
+    * If you use the CacheMiddleware, put the LocaleMiddleware after it, because
+      it changes the Vary header and so should be run before the CacheMiddleware
+      in process_response.
 
 For example, your ``MIDDLEWARE_CLASSES`` might look like this::
 
@@ -515,10 +518,6 @@
 use the same ``compile-messages.py`` to produce the binary ``django.mo`` files that
 are used by ``gettext``.
 
-Application message files are a bit complicated to discover -- they need the
-``LocaleMiddleware``. If you don't use the middleware, only the Django message
-files and project message files will be processed.
-
 Finally, you should give some thought to the structure of your translation
 files. If your applications need to be delivered to other users and will
 be used in other projects, you might want to use app-specific translations.

Those are the two changes I thought would be needed.

[anonymous]

Ah, sorry, was on an older revision, only the "-"-lines with the app language files need to be done. I am currently not at home but on the road for this week and just didn't svn up yet ;-)

[Adrian Holovaty]

OK, I believe this is fixed....Please reopen if there are still any problems with the i18n docs!