docs: update user guide

Author: kenjis

user_guide_src/source/general/common_functions.rst

@@ -367,16 +367,18 @@ Miscellaneous Functions
 
 .. php:function:: route_to($method[, ...$params])
 
-    :param   string  $method: The named route alias, or name of the controller/method to match.
-    :param   int|string   $params: One or more parameters to be passed to be matched in the route. The last parameter allows you to set the locale.
+    :param   string       $method: Route name or Controller::method
+    :param   int|string   ...$params: One or more parameters to be passed to the route. The last parameter allows you to set the locale.
+    :returns: a route (URI path)
+    :rtype: string
 
     .. note:: This function requires the controller/method to have a route defined in **app/Config/routes.php**.
 
     Generates a route for you based on a controller::method combination. Will take parameters into effect, if provided.
 
     .. literalinclude:: common_functions/009.php
 
-    Generates a route for you based on a named route alias.
+    Generates a route for you based on a route name.
 
     .. literalinclude:: common_functions/010.php
 

user_guide_src/source/helpers/url_helper.rst

@@ -361,8 +361,8 @@ The following functions are available:
 
 .. php:function:: url_to($controller[, ...$args])
 
-    :param  string  $controller: Named route or Controller::method
-    :param  mixed   ...$args:    One or more parameters to be passed to the route
+    :param  string  $controller: Route name or Controller::method
+    :param  mixed   ...$args:    One or more parameters to be passed to the route. The last parameter allows you to set the locale.
     :returns: Absolute URL
     :rtype: string
 
@@ -380,6 +380,10 @@ The following functions are available:
     This is useful because you can still change your routes after putting links
     into your views.
 
+    Since v4.3.0, when you use ``{locale}`` in your route, you can optionally specify the locale value as the last parameter.
+
+    .. literalinclude:: url_helper/025.php
+
     For full details, see the :ref:`reverse-routing` and :ref:`using-named-routes`.
 
 .. php:function:: url_is($path)

user_guide_src/source/helpers/url_helper/025.php

@@ -0,0 +1,13 @@
+<?php
+
+// The route is defined as:
+$routes->add(
+    '{locale}/users/(:num)/gallery/(:num)',
+    'Galleries::showUserGallery/$1/$2',
+    ['as' => 'user_gallery']
+);
+
+?>
+
+<a href="<?= url_to('user_gallery', 15, 12, 'en') ?>">View Gallery</a>
+<!-- Result: 'http://example.com/en/users/15/gallery/12' -->