Features

--------

- A locale negotiator no longer needs to be registered explicitly. The
  default locale negotiator at
  ``repoze.bfg.i18n.default_locale_negotiator`` is now used
  unconditionally as... um, the default locale negotiator.

- The default locale negotiator has become more complex.

  * First, the negotiator looks for the ``_LOCALE_`` attribute of
    the request object (possibly set by an :term:`event listener`).
  
  * Then it looks for the ``request.params['_LOCALE_']`` value.

  * Then it looks for the ``request.cookies['_LOCALE_']`` value.

Backwards Incompatibilities
---------------------------

- The default locale negotiator now looks for the parameter named
  ``_LOCALE_`` rather than a parameter named ``locale`` in
  ``request.params``.

Behavior Changes
----------------

- A locale negotiator may now return ``None``, signifying that the
  default locale should be used.

Documentation
-------------

- Documentation concerning locale negotiation in the
  Internationalizationa and Localization chapter was updated.

4 files changed, 59 insertions, 26 deletions

diff --git a/repoze/bfg/configuration.py b/repoze/bfg/configuration.py
index 9fa3fe8b2..546a6978b 100644
--- a/repoze/bfg/configuration.py
+++ b/repoze/bfg/configuration.py
@@ -145,6 +145,10 @@ class Configurator(object):
     class.  The debug logger is used by :mod:`repoze.bfg` itself to
     log warnings and authorization debugging information.
 
+    If ``locale_negotiator`` is passed, it should be a
+    :term:`locale negotiator` implementation.  See
+    :ref:`custom_locale_negotiator`.
+
     """
     manager = manager # for testing injection
     venusian = venusian # for testing injection
@@ -367,9 +371,9 @@ class Configurator(object):
         initialization.
 
         ``setup_registry`` configures settings, a root factory,
-        security policies, renderers, and a debug logger using the
-        configurator's current registry, as per the descriptions in
-        the Configurator constructor."""
+        security policies, renderers, a debug logger, and a locale
+        negotiator using the configurator's current registry, as per
+        the descriptions in the Configurator constructor."""
         self._fix_registry()
         self._set_settings(settings)
         self._set_root_factory(root_factory)
diff --git a/repoze/bfg/i18n.py b/repoze/bfg/i18n.py
index e3b276331..640ee030b 100644
--- a/repoze/bfg/i18n.py
+++ b/repoze/bfg/i18n.py
@@ -96,14 +96,27 @@ class Localizer(object):
 
 
 def default_locale_negotiator(request):
-    """ The default :term:`locale negotiator`.  Returns a locale
-    name based on ``request.params.get('locale')`` or the
-    ``default_locale_name`` settings option; or ``en`` if all else
-    fails."""
-    locale_name = request.params.get('locale')
+    """ The default :term:`locale negotiator`.  Returns a locale name
+    or ``None``.
+
+    - First, the negotiator looks for the ``_LOCALE_`` attribute of
+      the request object (possibly set by an :term:`event listener`).
+  
+    - Then it looks for the ``request.params['_LOCALE_']`` value.
+
+    - Then it looks for the ``request.cookies['_LOCALE_']`` value.
+
+    - Finally, the negotiator returns ``None`` if the locale could not
+      be determined via any of the previous checks (when a locale
+      negotiator returns ``None``, it signifies that the
+      :term:`default locale` should be used.)
+    """
+    name = '_LOCALE_'
+    locale_name = getattr(request, name, None)
     if locale_name is None:
-        settings = get_settings() or {}
-        locale_name = settings.get('default_locale_name', 'en')
+        locale_name = request.params.get(name)
+        if locale_name is None:
+            locale_name = request.cookies.get(name)
     return locale_name
 
 def negotiate_locale_name(request):
@@ -113,12 +126,14 @@ def negotiate_locale_name(request):
         registry = request.registry
     except AttributeError:
         registry = get_current_registry()
-    negotiator = registry.queryUtility(ILocaleNegotiator)
-    if negotiator is None:
+    negotiator = registry.queryUtility(ILocaleNegotiator,
+                                       default=default_locale_negotiator)
+    locale_name = negotiator(request)
+
+    if locale_name is None:
         settings = get_settings() or {}
         locale_name = settings.get('default_locale_name', 'en')
-    else:
-        locale_name = negotiator(request)
+
     return locale_name
 
 def get_locale_name(request):
diff --git a/repoze/bfg/tests/test_configuration.py b/repoze/bfg/tests/test_configuration.py
index 0a443720f..16b590cdd 100644
--- a/repoze/bfg/tests/test_configuration.py
+++ b/repoze/bfg/tests/test_configuration.py
@@ -3518,6 +3518,8 @@ class DummyRequest:
     subpath = ()
     def __init__(self):
         self.environ = {'PATH_INFO':'/static'}
+        self.params = {}
+        self.cookies = {}
     def copy(self):
         return self
     def get_response(self, app):
diff --git a/repoze/bfg/tests/test_i18n.py b/repoze/bfg/tests/test_i18n.py
index fb79a802c..95017807f 100644
--- a/repoze/bfg/tests/test_i18n.py
+++ b/repoze/bfg/tests/test_i18n.py
@@ -94,6 +94,15 @@ class Test_negotiate_locale_name(unittest.TestCase):
         result = self._callFUT(request)
         self.assertEqual(result, 'settings')
 
+    def test_use_default_locale_negotiator(self):
+        from repoze.bfg.threadlocal import get_current_registry
+        registry = get_current_registry()
+        request = DummyRequest()
+        request.registry = registry
+        request._LOCALE_ = 'locale'
+        result = self._callFUT(request)
+        self.assertEqual(result, 'locale')
+
     def test_default_default(self):
         request = DummyRequest()
         result = self._callFUT(request)
@@ -219,24 +228,26 @@ class Test_default_locale_negotiator(unittest.TestCase):
         from repoze.bfg.i18n import default_locale_negotiator
         return default_locale_negotiator(request)
 
-    def test_from_settings(self):
-        from repoze.bfg.interfaces import ISettings
-        from repoze.bfg.threadlocal import get_current_registry
-        settings = {'default_locale_name':'dude'}
-        registry = get_current_registry()
-        registry.registerUtility(settings, ISettings)
+    def test_from_none(self):
         request = DummyRequest()
         result = self._callFUT(request)
-        self.assertEqual(result, 'dude')
-        
-    def test_settings_empty(self):
+        self.assertEqual(result, None)
+
+    def test_from_request_attr(self):
         request = DummyRequest()
+        request._LOCALE_ = 'foo'
         result = self._callFUT(request)
-        self.assertEqual(result, 'en')
-        
+        self.assertEqual(result, 'foo')
+
     def test_from_params(self):
         request = DummyRequest()
-        request.params['locale'] = 'foo'
+        request.params['_LOCALE_'] = 'foo'
+        result = self._callFUT(request)
+        self.assertEqual(result, 'foo')
+
+    def test_from_cookies(self):
+        request = DummyRequest()
+        request.cookies['_LOCALE_'] = 'foo'
         result = self._callFUT(request)
         self.assertEqual(result, 'foo')
 
@@ -370,6 +381,7 @@ class TestTranslations(unittest.TestCase):
 class DummyRequest(object):
     def __init__(self):
         self.params = {}
+        self.cookies = {}
 
 def dummy_negotiator(request):
     return 'bogus'