Document new utf8 option of Routing component

Author: mickaelandrieu

components/routing.rst

@@ -346,6 +346,44 @@ 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 utf8 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
+    The UTF8 support in route paths and requirements were added in Symfony 3.2
+
 Learn more
 ----------
 
@@ -360,3 +398,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