[#4989] Language tweaks and making the example simpler

Author: weaverryan

book/translation.rst

@@ -428,34 +428,27 @@ via the ``request`` object::
     {
         $locale = $request->getLocale();
     }
-    
-To store the user's locale in the session you may want to create a custom event listener and set the locale there::
+
+To set the user's locale, you may want to create a custom event listener
+so that it's set before any other parts of the system (i.e. the translator)
+need it::
 
         public function onKernelRequest(GetResponseEvent $event)
         {
             $request = $event->getRequest();
-            if (!$request->hasPreviousSession()) {
-                return;
-            }
 
-            // try to see if the locale has been set as a _locale routing parameter
-            if ($locale = $request->attributes->get('_locale')) {
-                $request->getSession()->set('_locale', $locale);
-            } else {
-                // if no explicit locale has been set on this request, use one from the session
-                $request->setLocale($request->getSession()->get('_locale', $this->defaultLocale));
-            }
+            // some logic to determine the $locale
+            $request->getSession()->set('_locale', $locale);
         }
 
 Read :doc:`/cookbook/session/locale_sticky_session` for more on the topic.
 
 .. note::
 
-    Setting the locale using the ``$request->setLocale()`` method won't affect 
-    rendering in the same action. The translator locale is set during the
-    ``kernel.request`` event. Either set the locale before the listener is called
-    (e.g. in a custom listener described above) or use the ``setLocale()`` method
-    of the ``translator`` service.
+    Setting the locale using ``$request->setLocale()`` in the controller
+    is too late to affect the translator. Either set the locale via a listener
+    (like above), the URL (see next) or call ``setLocale()`` directly on
+    the ``translator`` service.
 
 .. index::
    single: Translations; Fallback and default locale