Fixed #4030 -- Added ability to translate language names. Thanks to Antti Kaihola and Ramiro Morales for the initial patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14894 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 71 insertions, 5 deletions

diff --git a/docs/topics/i18n/internationalization.txt b/docs/topics/i18n/internationalization.txt
index 1bd5cb0cd0..c2bd6eb309 100644
--- a/docs/topics/i18n/internationalization.txt
+++ b/docs/topics/i18n/internationalization.txt
@@ -274,7 +274,7 @@ The result of a ``ugettext_lazy()`` call can be used wherever you would use a
 unicode string (an object with type ``unicode``) in Python. If you try to use
 it where a bytestring (a ``str`` object) is expected, things will not work as
 expected, since a ``ugettext_lazy()`` object doesn't know how to convert
-itself to a bytestring.  You can't use a unicode string inside a bytestring,
+itself to a bytestring. You can't use a unicode string inside a bytestring,
 either, so this is consistent with normal Python behavior. For example::
 
     # This is fine: putting a unicode proxy into a unicode string.
@@ -379,6 +379,26 @@ Using this decorator means you can write your function and assume that the
 input is a proper string, then add support for lazy translation objects at the
 end.
 
+.. versionadded:: 1.3
+
+Localized names of languages
+============================
+
+The ``get_language_info()`` function provides detailed information about
+languages::
+
+    >>> from django.utils.translation import get_language_info
+    >>> li = get_language_info('de')
+    >>> print li['name'], li['name_local'], li['bidi']
+    German Deutsch False
+
+The ``name`` and ``name_local`` attributes of the dictionary contain the name of
+the language in English and in the language itself, respectively.  The ``bidi``
+attribute is True only for bi-directional languages.
+
+The source of the language information is the ``django.conf.locale`` module.
+Similar access to this information is available for template code. See below.
+
 .. _specifying-translation-strings-in-template-code:
 
 Specifying translation strings: In template code
@@ -518,6 +538,49 @@ string, so they don't need to be aware of translations.
     translator might translate the string ``"yes,no"`` as ``"ja,nein"``
     (keeping the comma intact).
 
+.. versionadded:: 1.3
+
+You can also retrieve information about any of the available languages using
+provided template tags and filters. To get information about a single language,
+use the ``{% get_language_info %}`` tag::
+
+    {% get_language_info for LANGUAGE_CODE as lang %}
+    {% get_language_info for "pl" as lang %}
+
+You can then access the information::
+
+    Language code: {{ lang.code }}<br />
+    Name of language: {{ lang.name_local }}<br />
+    Name in English: {{ lang.name }}<br />
+    Bi-directional: {{ lang.bidi }}
+
+You can also use the ``{% get_language_info_list %}`` template tag to retrieve
+information for a list of languages (e.g. active languages as specified in
+:setting:`LANGUAGES`). See :ref:`the section about the set_language redirect
+view <set_language-redirect-view>` for an example of how to display a language
+selector using ``{% get_language_info_list %}``.
+
+In addition to :setting:`LANGUAGES` style nested tuples,
+``{% get_language_info_list %}`` supports simple lists of language codes.
+If you do this in your view:
+
+.. code-block:: python
+
+    return render_to_response('mytemplate.html', {
+        'available_languages': ['en', 'es', 'fr'],
+    }, RequestContext(request))
+
+you can iterate over those languages in the template::
+
+  {% get_language_info_list for available_languages as langs %}
+  {% for lang in langs %} ... {% endfor %}
+
+There are also simple filters available for convenience:
+
+    * ``{{ LANGUAGE_CODE|language_name }}`` ("German")
+    * ``{{ LANGUAGE_CODE|language_name_local }}`` ("Deutsch")
+    * ``{{ LANGUAGE_CODE|bidi }}`` (False)
+
 .. _Django templates: ../templates_python/
 
 Specifying translation strings: In JavaScript code
@@ -579,7 +642,7 @@ With this, you specify the packages as a list of package names delimited by '+'
 signs in the URL. This is especially useful if your pages use code from
 different apps and this changes often and you don't want to pull in one big
 catalog file. As a security measure, these values can only be either
-``django.conf`` or any package from the ``INSTALLED_APPS`` setting.
+``django.conf`` or any package from the :setting:`INSTALLED_APPS` setting.
 
 Using the JavaScript translation catalog
 ----------------------------------------
@@ -636,6 +699,8 @@ This isn't as fast as string interpolation in Python, so keep it to those
 cases where you really need it (for example, in conjunction with ``ngettext``
 to produce proper pluralizations).
 
+.. _set_language-redirect-view:
+
 The ``set_language`` redirect view
 ==================================
 
@@ -654,7 +719,7 @@ The view expects to be called via the ``POST`` method, with a ``language``
 parameter set in request. If session support is enabled, the view
 saves the language choice in the user's session. Otherwise, it saves the
 language choice in a cookie that is by default named ``django_language``.
-(The name can be changed through the ``LANGUAGE_COOKIE_NAME`` setting.)
+(The name can be changed through the :setting:`LANGUAGE_COOKIE_NAME` setting.)
 
 After setting the language choice, Django redirects the user, following this
 algorithm:
@@ -673,8 +738,9 @@ Here's example HTML template code:
     {% csrf_token %}
     <input name="next" type="hidden" value="/next/page/" />
     <select name="language">
-    {% for lang in LANGUAGES %}
-    <option value="{{ lang.0 }}">{{ lang.1 }}</option>
+    {% get_language_info_list for LANGUAGES as languages %}
+    {% for language in languages %}
+    <option value="{{ language.code }}">{{ language.name_local }} ({{ language.code }})</option>
     {% endfor %}
     </select>
     <input type="submit" value="Go" />