Merge branch '2.3' into 2.4

Conflicts:
	book/security.rst
	components/security/authentication.rst
	components/translation/introduction.rst

Author: weaverryan

book/http_cache.rst

@@ -474,7 +474,7 @@ The resulting HTTP header will look like this:
 
 Note that in HTTP versions before 1.1 the origin server wasn't required to
 send the ``Date`` header. Consequently the cache (e.g. the browser) might
-need to rely onto his local clock to evaluate the ``Expires`` header making
+need to rely on the local clock to evaluate the ``Expires`` header making
 the lifetime calculation vulnerable to clock skew. Another limitation
 of the ``Expires`` header is that the specification states that "HTTP/1.1
 servers should not send ``Expires`` dates more than one year in the future."

book/installation.rst

@@ -341,7 +341,7 @@ file:
 
 Now, the vendor directory won't be committed to source control. This is fine
 (actually, it's great!) because when someone else clones or checks out the
-project, he/she can simply run the ``php composer.phar install`` script to
+project, they can simply run the ``php composer.phar install`` script to
 install all the necessary project dependencies.
 
 .. _`enable ACL support`: https://help.ubuntu.com/community/FilePermissionsACLs

book/security.rst

@@ -5,7 +5,7 @@ Security
 ========
 
 Security is a two-step process whose goal is to prevent a user from accessing
-a resource that he/she should not have access to.
+a resource that they should not have access to.
 
 In the first step of the process, the security system identifies who the user
 is by requiring the user to submit some sort of identification. This is called
@@ -165,7 +165,7 @@ Firewalls (Authentication)
 
 When a user makes a request to a URL that's protected by a firewall, the
 security system is activated. The job of the firewall is to determine whether
-or not the user needs to be authenticated, and if he does, to send a response
+or not the user needs to be authenticated, and if they do, to send a response
 back to the user initiating the authentication process.
 
 A firewall is activated when the URL of an incoming request matches the configured
@@ -217,7 +217,7 @@ If the credentials are valid, the original request can be re-tried.
    :align: center
 
 In this example, the user ``ryan`` successfully authenticates with the firewall.
-But since ``ryan`` doesn't have the ``ROLE_ADMIN`` role, he's still denied
+But since ``ryan`` doesn't have the ``ROLE_ADMIN`` role, they're still denied
 access to ``/admin/foo``. Ultimately, this means that the user will see some
 sort of message indicating that access has been denied.
 
@@ -1041,7 +1041,7 @@ Access Control Lists (ACLs): Securing Individual Database Objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Imagine you are designing a blog system where your users can comment on your
-posts. Now, you want a user to be able to edit his own comments, but not
+posts. Now, you want a user to be able to edit their own comments, but not
 those of other users. Also, as the admin user, you yourself want to be able
 to edit *all* comments.
 
@@ -1800,7 +1800,7 @@ a route so that you can use it to generate the URL:
 
         return $collection;
 
-Once the user has been logged out, he will be redirected to whatever path
+Once the user has been logged out, they will be redirected to whatever path
 is defined by the ``target`` parameter above (e.g. the ``homepage``). For
 more information on configuring the logout, see the
 :doc:`Security Configuration Reference </reference/configuration/security>`.

book/templating.rst

@@ -1359,7 +1359,7 @@ this classic example:
 
         Hello <?php echo $name ?>
 
-Imagine that the user enters the following code as his/her name:
+Imagine the user enters the following code for their name:
 
 .. code-block:: text
 

book/translation.rst

@@ -22,8 +22,8 @@ into the language of the user::
 
     The term *locale* refers roughly to the user's language and country. It
     can be any string that your application uses to manage translations and
-    other format differences (e.g. currency format). The `ISO639-1`_
-    *language* code, an underscore (``_``), then the `ISO3166 Alpha-2`_
+    other format differences (e.g. currency format). The `ISO 639-1`_
+    *language* code, an underscore (``_``), then the `ISO 3166-1 alpha-2`_
     *country* code (e.g. ``fr_FR`` for French/France) is recommended.
 
 In this chapter, you'll learn how to use the Translation component in the
@@ -41,7 +41,8 @@ to learn even more. Overall, the process has several steps:
    for each supported locale that translate each message in the application;
 
 #. Determine, :ref:`set and manage the user's locale <book-translation-user-locale>`
-   for the request and optionally on the user's entire session.
+   for the request and optionally
+   :doc:`on the user's entire session </cookbook/session/locale_sticky_session>`.
 
 .. _book-translation-configuration:
 
@@ -147,11 +148,12 @@ different formats, XLIFF being the recommended format:
         # messages.fr.yml
         Symfony2 is great: J'aime Symfony2
 
-For information on where these files should be located, see :ref:`book-translation-resource-locations`.
+For information on where these files should be located, see
+:ref:`book-translation-resource-locations`.
 
 Now, if the language of the user's locale is French (e.g. ``fr_FR`` or ``fr_BE``),
 the message will be translated into ``J'aime Symfony2``. You can also translate
-message inside your :ref:`templates <book-translation-tags>`.
+the message inside your :ref:`templates <book-translation-tags>`.
 
 The Translation Process
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -278,8 +280,8 @@ texts* and complex expressions:
     Using the translation tags or filters have the same effect, but with
     one subtle difference: automatic output escaping is only applied to
     translations using a filter. In other words, if you need to be sure
-    that your translated is *not* output escaped, you must apply the
-    ``raw`` filter after the translation filter:
+    that your translated message is *not* output escaped, you must apply
+    the ``raw`` filter after the translation filter:
 
     .. code-block:: jinja
 
@@ -290,7 +292,7 @@ texts* and complex expressions:
 
             {% set message = '<h3>foo</h3>' %}
 
-            {# strings and variables translated via a filter is escaped by default #}
+            {# strings and variables translated via a filter are escaped by default #}
             {{ message|trans|raw }}
             {{ '<h3>bar</h3>'|trans|raw }}
 
@@ -303,7 +305,7 @@ texts* and complex expressions:
            {% trans_default_domain "app" %}
 
     Note that this only influences the current template, not any "included"
-    templates (in order to avoid side effects).
+    template (in order to avoid side effects).
 
 PHP Templates
 ~~~~~~~~~~~~~
@@ -346,7 +348,7 @@ The filename of the translation files is also important: each message file
 must be named according to the following path: ``domain.locale.loader``:
 
 * **domain**: An optional way to organize messages into groups (e.g. ``admin``,
-  ``navigation`` or the default ``messages``) - see ":ref:`using-message-domains`";
+  ``navigation`` or the default ``messages``) - see :ref:`using-message-domains`;
 
 * **locale**: The locale that the translations are for (e.g. ``en_GB``, ``en``, etc);
 
@@ -374,7 +376,7 @@ taste. For more options, see :ref:`component-translator-message-catalogs`.
 
     Each time you create a *new* translation resource (or install a bundle
     that includes a translation resource), be sure to clear your cache so
-    that Symfony can discover the new translation resource:
+    that Symfony can discover the new translation resources:
 
     .. code-block:: bash
 
@@ -481,11 +483,13 @@ by the routing system using the special ``_locale`` parameter:
         return $collection;
 
 When using the special ``_locale`` parameter in a route, the matched locale
-will *automatically be set on the user's session*. In other words, if a user
+will *automatically be set on the Request* and can be retrieved via the
+:method:`Symfony\\Component\\HttpFoundation\\Request::getLocale` method.
+In other words, if a user
 visits the URI ``/fr/contact``, the locale ``fr`` will automatically be set
-as the locale for the user's session.
+as the locale for the current request.
 
-You can now use the user's locale to create routes to other translated pages
+You can now use the locale to create routes to other translated pages
 in your application.
 
 Setting a Default Locale
@@ -651,7 +655,7 @@ steps:
 * Abstract messages in your application by wrapping each in either the
   :method:`Symfony\\Component\\Translation\\Translator::trans` or
   :method:`Symfony\\Component\\Translation\\Translator::transChoice` methods
-  (learn about this in ":doc:`/components/translation/usage`");
+  (learn about this in :doc:`/components/translation/usage`);
 
 * Translate each message into multiple locales by creating translation message
   files. Symfony2 discovers and processes each file because its name follows
@@ -661,6 +665,6 @@ steps:
   be set on the user's session.
 
 .. _`i18n`: http://en.wikipedia.org/wiki/Internationalization_and_localization
-.. _`ISO3166 Alpha-2`: http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
-.. _`ISO639-1`: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+.. _`ISO 3166-1 alpha-2`: http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
+.. _`ISO 639-1`: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
 .. _`Translatable Extension`: https://github.com/l3pp4rd/DoctrineExtensions

book/validation.rst

@@ -692,7 +692,7 @@ on that class. To do this, you can organize each constraint into one or more
 constraints.
 
 For example, suppose you have a ``User`` class, which is used both when a
-user registers and when a user updates his/her contact information later:
+user registers and when a user updates their contact information later:
 
 .. configuration-block::
 

components/console/helpers/dialoghelper.rst

@@ -49,8 +49,8 @@ if you want to know a bundle name, you can add this to your command::
         'AcmeDemoBundle'
     );
 
-The user will be asked "Please enter the name of the bundle". She can type
-some name which will be returned by the ``ask`` method. If she leaves it empty,
+The user will be asked "Please enter the name of the bundle". They can type
+some name which will be returned by the ``ask`` method. If they leave it empty,
 the default value (``AcmeDemoBundle`` here) is returned.
 
 Autocompletion
@@ -138,8 +138,8 @@ function should also return the value of the user's input if the validation was
 You can set the max number of times to ask in the ``$attempts`` argument.
 If you reach this max number it will use the default value, which is given
 in the last argument. Using ``false`` means the amount of attempts is infinite.
-The user will be asked as long as he provides an invalid answer and will only
-be able to proceed if her input is valid.
+The user will be asked as long as they provide an invalid answer and will only
+be able to proceed if their input is valid.
 
 Validating a Hidden Response
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -202,7 +202,7 @@ The option which should be selected by default is provided with the fourth
 argument. The default is ``null``, which means that no option is the default one.
 
 If the user enters an invalid string, an error message is shown and the user
-is asked to provide the answer another time, until she enters a valid string
+is asked to provide the answer another time, until they enter a valid string
 or the maximum attempts is reached (which you can define in the fifth
 argument). The default value for the attempts is ``false``, which means infinite
 attempts. You can define your own error message in the sixth argument.

components/event_dispatcher/container_aware_dispatcher.rst

@@ -2,7 +2,7 @@
    single: EventDispatcher; Service container aware
 
 The Container Aware Event Dispatcher
-===================================
+====================================
 
 Introduction
 ------------

components/event_dispatcher/introduction.rst

@@ -11,7 +11,7 @@ Introduction
 Objected Oriented code has gone a long way to ensuring code extensibility. By
 creating classes that have well defined responsibilities, your code becomes
 more flexible and a developer can extend them with subclasses to modify their
-behaviors. But if he wants to share his changes with other developers who have
+behaviors. But if they want to share the changes with other developers who have
 also made their own subclasses, code inheritance is no longer the answer.
 
 Consider the real-world example where you want to provide a plugin system for

components/form/introduction.rst

@@ -487,7 +487,7 @@ method:
 
     .. code-block:: php-standalone
 
-        use Symfony\HttpFoundation\Request;
+        use Symfony\Component\HttpFoundation\Request;
         use Symfony\Component\HttpFoundation\RedirectResponse;
 
         $form = $formFactory->createBuilder()

components/security/authentication.rst

@@ -110,7 +110,7 @@ Authenticating Users by their Username and Password
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 An authentication provider will attempt to authenticate a user based on
-the credentials he provided. Usually these are a username and a password.
+the credentials they provided. Usually these are a username and a password.
 Most web applications store their user's username and a hash of the user's
 password combined with a randomly generated salt. This means that the average
 authentication would consist of fetching the salt and the hashed password
@@ -225,4 +225,4 @@ which should be used to encode this user's password::
         $password,
         $user->getSalt());
 
-.. _`CVE-2013-5750`: http://symfony.com/blog/cve-2013-5750-security-issue-in-fosuserbundle-login-form
+.. _`CVE-2013-5750`: http://symfony.com/blog/cve-2013-5750-security-issue-in-fosuserbundle-login-form

components/security/firewall.rst

@@ -101,7 +101,7 @@ firewall map will jump in.
 
 The exception listener determines what happens next, based on the arguments
 it received when it was created. It may start the authentication procedure,
-perhaps ask the user to supply his credentials again (when he has only been
+perhaps ask the user to supply their credentials again (when they have only been
 authenticated based on a "remember-me" cookie), or transform the exception
 into an :class:`Symfony\\Component\\HttpKernel\\Exception\\AccessDeniedHttpException`,
 which will eventually result in an "HTTP/1.1 403: Access Denied" response.
@@ -119,7 +119,7 @@ object and the exception by which the exception listener was triggered.
 The method should return a :class:`Symfony\\Component\\HttpFoundation\\Response`
 object. This could be, for instance, the page containing the login form or,
 in the case of Basic HTTP authentication, a response with a ``WWW-Authenticate``
-header, which will prompt the user to supply his username and password.
+header, which will prompt the user to supply their username and password.
 
 Flow: Firewall, Authentication, Authorization
 ---------------------------------------------

components/translation/introduction.rst

@@ -13,13 +13,13 @@ Installation
 
 You can install the component in 2 different ways:
 
-* :doc:`Install it via Composer</components/using_components>` (``symfony/translation`` on `Packagist`_).
-* Use the official Git repository (https://github.com/symfony/Translation);
+* :doc:`Install it via Composer </components/using_components>` (``symfony/translation`` on `Packagist`_);
+* Use the official Git repository (https://github.com/symfony/Translation).
 
 Constructing the Translator
 ---------------------------
 
-The main access point of the Translation Component is
+The main access point of the Translation component is
 :class:`Symfony\\Component\\Translation\\Translator`. Before you can use it,
 you need to configure it and load the messages to translate (called *message
 catalogs*).
@@ -45,8 +45,8 @@ The constructor of the ``Translator`` class needs one argument: The locale.
 
     The term *locale* refers roughly to the user's language and country. It
     can be any string that your application uses to manage translations and
-    other format differences (e.g. currency format). The `ISO639-1`_
-    *language* code, an underscore (``_``), then the `ISO3166 Alpha-2`_
+    other format differences (e.g. currency format). The `ISO 639-1`_
+    *language* code, an underscore (``_``), then the `ISO 3166-1 alpha-2`_
     *country* code (e.g. ``fr_FR`` for French/France) is recommended.
 
 .. _component-translator-message-catalogs:
@@ -59,7 +59,7 @@ class. A message catalog is like a dictionary of translations for a specific
 locale.
 
 The Translation component uses Loader classes to load catalogs. You can load
-multiple resources for the same locale, it will be combined into one
+multiple resources for the same locale, which will then be combined into one
 catalog.
 
 The component comes with some default Loaders and you can create your own
@@ -88,7 +88,7 @@ Loader too. The default loaders are:
 * :class:`Symfony\\Component\\Translation\\Loader\\YamlFileLoader` - to load
   catalogs from Yaml files (requires the :doc:`Yaml component</components/yaml/introduction>`).
 
-All file loaders require the :doc:`Config component</components/config/index>`.
+All file loaders require the :doc:`Config component </components/config/index>`.
 
 At first, you should add one or more loaders to the ``Translator``::
 
@@ -198,8 +198,8 @@ specified locale.
 Usage
 -----
 
-Read how to use the Translation component in ":doc:`/components/translation/usage`".
+Read how to use the Translation component in :doc:`/components/translation/usage`.
 
 .. _Packagist: https://packagist.org/packages/symfony/translation
-.. _`ISO3166 Alpha-2`: http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
-.. _`ISO639-1`: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+.. _`ISO 3166-1 alpha-2`: http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
+.. _`ISO 639-1`: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

components/translation/usage.rst

@@ -14,7 +14,7 @@ Imagine you want to translate the string *"Symfony2 is great"* into French::
     $translator->addResource('array', array(
         'Symfony2 is great!' => 'J\'aime Symfony2!',
     ), 'fr_FR');
-    
+
     echo $translator->trans('Symfony2 is great!');
 
 In this example, the message *"Symfony2 is great!"* will be translated into
@@ -81,7 +81,7 @@ is done just as before:
 
     The placeholders can take on any form as the full message is reconstructed
     using the PHP :phpfunction:`strtr function<strtr>`. But the ``%...%`` form
-    is recommend, to avoid problems when using Twig.
+    is recommended, to avoid problems when using Twig.
 
 As you've seen, creating a translation is a two-step process:
 
@@ -257,7 +257,7 @@ To translate pluralized messages, use the
         array('%count%' => 10)
     );
 
-The second argument (``10`` in this example), is the *number* of objects being
+The second argument (``10`` in this example) is the *number* of objects being
 described and is used to determine which translation to use and also to populate
 the ``%count%`` placeholder.
 

contributing/documentation/overview.rst

@@ -178,10 +178,6 @@ Translating
 
 Read the dedicated :doc:`document <translations>`.
 
-.. _`fork`: https://help.github.com/articles/fork-a-repo
-.. _`pull requests`: https://help.github.com/articles/using-pull-requests
-.. _`Documentation Build Errors`: http://symfony.com/doc/build_errors
-
 Managing Releases
 -----------------
 
@@ -226,4 +222,7 @@ happens, the following items are done:
   For example, in installation chapters, we reference the version you should
   use for installation. As an example, see the changes made in `PR #2688`_.
 
-.. _`PR #2688`: https://github.com/symfony/symfony-docs/pull/2688
+.. _`fork`:                       https://help.github.com/articles/fork-a-repo
+.. _`pull requests`:              https://help.github.com/articles/using-pull-requests
+.. _`Documentation Build Errors`: http://symfony.com/doc/build_errors
+.. _`PR #2688`:                   https://github.com/symfony/symfony-docs/pull/2688