From 87be2ebc7fbe82febb0b80381e21cb0132787b55 Mon Sep 17 00:00:00 2001 From: Frank de Jonge Date: Wed, 28 Mar 2018 22:38:30 +0200 Subject: [PATCH 1/4] Initial docs on i18n routing. --- routing.rst | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/routing.rst b/routing.rst index 40a3946bcd1..1629ee60243 100644 --- a/routing.rst +++ b/routing.rst @@ -136,6 +136,89 @@ use them later to :ref:`generate URLs `. 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 + + + + + + + /over-ons + /about-us + + + + .. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From f7c883984c877d105eb770d1ad0e6ecf2b18f927 Mon Sep 17 00:00:00 2001 From: Frank de Jonge Date: Thu, 29 Mar 2018 14:45:48 +0200 Subject: [PATCH 2/4] handle => handy --- routing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/routing.rst b/routing.rst index 1629ee60243..f5a7a30262d 100644 --- a/routing.rst +++ b/routing.rst @@ -142,7 +142,7 @@ Localized Routing (i18n) ------------------------ Routes can be localized to provide unique paths per *locale*. Symfony provides a -handle way to declare localized routes without duplication. +handy way to declare localized routes without duplication. .. configuration-block:: From 2341bf904d166bce0fca6b3fcb9c17e678c900c3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 27 May 2018 19:37:05 +0200 Subject: [PATCH 3/4] Minor rewords and fixes --- routing.rst | 43 +++++++++++++++++-------------------------- 1 file changed, 17 insertions(+), 26 deletions(-) diff --git a/routing.rst b/routing.rst index f5a7a30262d..ef6313c0089 100644 --- a/routing.rst +++ b/routing.rst @@ -141,8 +141,11 @@ use them later to :ref:`generate URLs `. Localized Routing (i18n) ------------------------ -Routes can be localized to provide unique paths per *locale*. Symfony provides a -handy way to declare localized routes without duplication. +.. versionadded:: 4.1 + The feature to localize routes was introduced in Symfony 4.1. + +Routes can be localized to provide unique paths per :doc:`locale `. +Symfony provides a handy way to declare localized routes without duplication. .. configuration-block:: @@ -154,30 +157,18 @@ handy way to declare localized routes without duplication. use Symfony\Bundle\FrameworkBundle\Controller\Controller; use Symfony\Component\Routing\Annotation\Route; - class BlogController extends Controller + class CompanyController extends Controller { /** - * Matches /blog exactly - * - * @Route("/blog", name="blog_list") + * @Route({ + * "nl": "/over-ons", + * "en": "/about-us" + * }, name="about_us") */ - public function list() + public function about() { // ... } - - /** - * 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 @@ -214,7 +205,7 @@ handy way to declare localized routes without duplication. ->controller('App\Controller\CompanyController::about'); }; -When a localized route is matched Symfony will automatically know which locale +When a localized route is matched Symfony automatically knows 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. @@ -695,16 +686,16 @@ 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:: +When a route is localized, Symfony uses by default the current request locale to +generate the URL. In order to generate the route for a different locale you must +pass the ``_locale`` in the parameters array:: $this->router->generate('about_us', array( '_locale' => 'nl', )); - // /over-ons + // generates: /over-ons Generating URLs from a Template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From fe8027ca0f1ffca48db4f795f346d82cc3340c3f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 27 May 2018 19:38:25 +0200 Subject: [PATCH 4/4] Minor tweak --- routing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/routing.rst b/routing.rst index ef6313c0089..6e4334e16c0 100644 --- a/routing.rst +++ b/routing.rst @@ -689,7 +689,7 @@ Generating Localized URLs ~~~~~~~~~~~~~~~~~~~~~~~~~ When a route is localized, Symfony uses by default the current request locale to -generate the URL. In order to generate the route for a different locale you must +generate the URL. In order to generate the URL for a different locale you must pass the ``_locale`` in the parameters array:: $this->router->generate('about_us', array(