Document new utf8 option of Routing component

Author: mickaelandrieu

components/routing.rst

@@ -346,6 +346,59 @@ automatically in the background if you want to use it. A basic example of the
     are saved in the ``cache_dir``. This means your script must have write
     permissions for that location.
 
+Unicode Routing support
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The Routing component supports UTF-8 characters in route paths and requirements.
+Thanks to the ``utf8`` route option, you can make Symfony match and generate
+routes with UTF-8 characters:
+
+.. code-block:: yaml
+
+    # routes.yml
+    route1:
+        path:     /category/{name}
+        defaults: { _controller: 'DefaultController::categoryAction' }
+        requirements:
+          name: ".+"
+        options:
+          utf8: true
+
+In this route, the ``utf8`` option set to true makes Symfony consider the
+``.`` requirement to match any UTF-8 characters instead of just a single
+byte character, so the following URLs would match: ``/category/日本語``,
+``/category/فارسی``, ``/category/한국어``, etc. In case you are wondering,
+this option also allows to include and match emojis in URLs.
+
+.. code-block:: yaml
+
+    # routes.yml
+    route2:
+        path:     /default/{default}
+        defaults: { _controller: 'DefaultController::defaultAction' }
+        requirements:
+          default: "日本語|فارسی"
+        options:
+          utf8: true
+
+This second example describes how you can use UTF-8 string as a routing
+requirement.
+
+.. note::
+
+    In Symfony 3.2 there is no need to set this utf8 explicitly. As soon
+    as Symfony finds a UTF-8 character in the route path or requirements,
+    it will turn the UTF-8 support automatically. In addition to UTF-8
+    characters, the Routing component also supports all the `PCRE Unicode properties`_,
+    which are escape sequences that match generic character types. For
+    example, ``\p{Lu}`` matches any uppercase character in any language,
+    ``\p{Greek}`` matches any Greek character, ``\P{Han}`` matches any character
+    not included in the Chinese Han script.
+
+.. versionadded:: 3.2
+    UTF-8 support for route paths and requirements were introduced in
+    Symfony 3.2.
+
 Learn more
 ----------
 
@@ -360,3 +413,4 @@ Learn more
     /configuration/apache_router
 
 .. _Packagist: https://packagist.org/packages/symfony/routing
+.. _PCRE Unicode properties: http://php.net/manual/en/regexp.reference.unicode.php