i18n: updated documentation and unittests for the new get_available_languages tag and the new switching view

git-svn-id: http://code.djangoproject.com/svn/django/branches/i18n@1049 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 31 insertions, 24 deletions

diff --git a/docs/translation.txt b/docs/translation.txt
index c727cc3ad0..54c5a4b512 100644
--- a/docs/translation.txt
+++ b/docs/translation.txt
@@ -155,21 +155,34 @@ is a list of tuples where the first element is the language code and the
 second element is the language name (in that language). The code might
 look like this::
 
-    <form method="POST">
-    <select name="django_language">
+    <form action="/i18n/setlang/" method="POST">
+    <input name="next" type="hidden" value="http://server.doma.in/path/to/go/to/after/switch/"/>
+    <select name="language">
     {% for lang in LANGUAGES %}
     <option value="{{ lang.0 }}">{{ lang.1 }}</option>
     {% endfor %}
     </select>
     </form>
 
-This would jump to the same page you came from and pass the django_language
-variable. This is used in discovery of languages, as described in the next
-chapter. Of course this can only work if your rendering context contains
-the LANGUAGE_CODE and LANGUAGES variables. If you use DjangoContext as
-your rendering context, they are automatically defined. If you use the
-simpler Context class, you need to pass them along from request.LANGUAGE_CODE
-and settings.LANGUAGES themselve.
+This would jump to a language switcher and then be redirected back to the
+page it came from. The switcher page will just store the language in either
+the users session or a special cookie for use in the language discovery.
+
+You can leave out the "next" field. In that case the /i18n/setlang/ view
+will redirect to the URL that is in the "Referer" header. Please keep in mind
+that people might suppress that header, so in those cases there won't be a
+URL to redirect to - in those cases the view function will redirect to "/"
+as a fallback.
+
+The /i18n/setlang/ url can be set up by including the following in your
+ROOT_URLCONF::
+
+    urlpatterns = patterns('',
+        (r'^i18n/', include('django.conf.urls.i18n'),
+    )
+
+This adds the setlang handler to your urlspace and hooks up a standard view
+function to it.
 
 How the Language is Discovered
 ==============================
@@ -206,20 +219,11 @@ from the admin.py settings file).
 The LocaleMiddleware allows a selection of the language based on data from
 the request - every user can have her own settings.
 
-The first thing the LocaleMiddleware does, is looking at the GET and POST
-data. If it finds a django_language variable there (if both have one, the
-one from GET will succeed), this language will be stored in the session
-(if sessions are used in your site) or in a cookie (if you don't use
-sessions). And it will be the selected langauge, of course. That way
-you can provide simple language switches by creating either a link with
-language (linked from country flags for example) or by giving the user some
-language selector like in the previous chapter.
-
-If neither GET nor POST have django_language, the middleware looks at the
-session data for the user. If that carries a key django_language, it's contents
-will be used as the language code. If the session doesn't contain a language
-setting, the middleware will look at the cookies for a django_language cookie.
-If that is found, it gives the language code.
+The first thing the LocaleMiddleware does, it looks at the session data for the
+user. If that carries a key django_language, it's contents will be used as the
+language code. If the session doesn't contain a language setting, the
+middleware will look at the cookies for a django_language cookie.  If that is
+found, it gives the language code.
 
 The format for the explicit django_language parameters is allways the
 language to use - for example it's pt-br for Brazilian. If a base language
diff --git a/tests/othertests/templates.py b/tests/othertests/templates.py
index 190685a42c..e2afad5777 100644
--- a/tests/othertests/templates.py
+++ b/tests/othertests/templates.py
@@ -258,6 +258,9 @@ TEMPLATE_TESTS = {
 
     # translation of a variable with a non-translated filter
     'i18n14': ('{{ bool|yesno:"ja,nein" }}', {'bool': True}, 'ja'),
+
+    # usage of the get_available_languages tag
+    'i18n15': ('{% get_available_languages as langs %}{% for lang in langs %}{% ifequal lang.0 "de" %}{{ lang.0 }}{% endifequal %}{% endfor %}', {}, 'de'),
 }
 
 def test_template_loader(template_name, template_dirs=None):
@@ -277,7 +280,7 @@ def run_tests(verbosity=0, standalone=False):
     tests.sort()
     for name, vals in tests:
         if 'LANGUAGE_CODE' in vals[1]:
-            activate('*', vals[1]['LANGUAGE_CODE'])
+            activate(vals[1]['LANGUAGE_CODE'])
         try:
             output = loader.get_template(name).render(template.Context(vals[1]))
         except Exception, e: