Initial docs on i18n routing.

Author: frankdejonge

routing.rst

@@ -136,6 +136,89 @@ use them later to :ref:`generate URLs <routing-generate>`.
     configure your routes in YAML, XML or PHP, that's no problem! Just create a
     new routing file (e.g. ``routes.xml``) and Symfony will automatically use it.
 
+.. _i18n-routing:
+
+Localized Routing (i18n)
+------------------------
+
+Routes can be localized to provide unique paths per *locale*. Symfony provides a
+handle way to declare localized routes without duplication.
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Controller/BlogController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class BlogController extends Controller
+        {
+            /**
+             * Matches /blog exactly
+             *
+             * @Route("/blog", name="blog_list")
+             */
+            public function list()
+            {
+                // ...
+            }
+
+            /**
+             * Matches /blog/*
+             *
+             * @Route("/blog/{slug}", name="blog_show")
+             */
+            public function show($slug)
+            {
+                // $slug will equal the dynamic part of the URL
+                // e.g. at /blog/yay-routing, then $slug='yay-routing'
+
+                // ...
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        about_us:
+            path:
+                nl: /over-ons
+                en: /about-us
+            controller: App\Controller\CompanyController::about
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                http://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="about_us" controller="App\Controller\CompanyController::about">
+                <path locale="nl">/over-ons</path>
+                <path locale="en">/about-us</path>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        namespace Symfony\Component\Routing\Loader\Configurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('about_us', ['nl' => '/over-ons', 'en' => '/about-us'])
+                ->controller('App\Controller\CompanyController::about');
+        };
+
+When a localized route is matched Symfony will automatically know which locale
+should be used during the request. Defining routes this way also eliminated the
+need for duplicate registration of routes which minimizes the risk for any bugs
+caused by definition inconsistency.
+
 .. _routing-requirements:
 
 Adding {wildcard} Requirements
@@ -611,6 +694,18 @@ But if you pass extra ones, they will be added to the URI as a query string::
     ));
     // /blog/2?category=Symfony
 
+Generating Localized URLs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you've defined localized routes Symfony will use the current request locale
+as the default when generating routes. In order to generate the route for alternative
+locale you must pass the ``_locale`` in the parameters array::
+
+    $this->router->generate('about_us', array(
+        '_locale' => 'nl',
+    ));
+    // /over-ons
+
 Generating URLs from a Template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~