docs: dev/web: update i18n docs

docs/dev/web/controller.rst

@@ -4,15 +4,19 @@ Controllers
 Controllers live in ``/lib/gluon/web/controller``. They define which pages ("routes")
 exist under the ``/cgi-bin/gluon`` path, and what code is run when these pages are requested.
 
-Controller scripts mostly consist of calls of the `entry` function, which each define
+Controller scripts usually start with a *package* declaration, followed by calls
-one route:
+to the *entry* function, which each define one route:
 
 .. code-block:: lua
 
+  package 'gluon-web-admin'
+
   entry({"admin"}, alias("admin", "info"), _("Advanced settings"), 10)
   entry({"admin", "info"}, template("admin/info"), _("Information"), 1)
 
-The entry function expects 4 arguments:
+*package* defines the translation namespace for the titles of the defined
+pages as well as the referenced views and models. The entry function expects 4
+arguments:
 
   - `path`: Components of the path to define a route for.
 
@@ -20,6 +24,7 @@ The entry function expects 4 arguments:
 
   - `target`: Dispatcher for the route. See the following section for details.
   - `title`: Page title (also used in navigation). The underscore function is used
+    to mark the strings as translatable for ``i18n-scan.pl``.
 
   - `order`: Sort index in navigation (defaults to 100)
 
@@ -88,9 +93,10 @@ The template renderer
 The template renderer allows to render templates (views). The most useful functions
 are:
 
-  - *render* (*view*, *scope*): Renders the given view, optionally passing a table
+  - *render* (*view*, *scope*, *pkg*): Renders the given view, optionally passing a table
-    with additional variables to make available in the template.
+    with additional variables to make available in the template. The passed package
-  - *render_string* (*str*, *scope*): Same as *render*, but the template is passed
+    defines the translation namespace.
+  - *render_string* (*str*, *scope*, *pkg*): Same as *render*, but the template is passed
     directly instead of being loaded from the view directory.
 
 The renderer functions are called in property syntax, for example:

docs/dev/web/i18n.rst

@@ -20,8 +20,9 @@ Internationalization support is available in all components (models, view and
 controllers) of *gluon-web*-based packages. Strings are translated using the *translate*,
 *_translate* and *translatef* functions (*translate* for static strings, *translatef*
 for printf-like formatted string; *_translate* works the same as *translate*, but
-will return *nil* instead of the original string when no translation is available)
+will return *nil* instead of the original string when no translation is available).
-. In views, the special tags ``<%:...%>`` can be used to translate the contained string.
+
+In views, the special tags ``<%:...%>`` can be used to translate the contained string.
 
 Example from the *gluon-config-mode-geo-location* package:
 
@@ -29,6 +30,18 @@ Example from the *gluon-config-mode-geo-location* package:
 
   local share_location = s:option(Flag, "location", translate("Show node on the map"))
 
+Note that translations are *namespaced*: each package will only use its own
+translation strings by default. For this purpose, the package name must by
+specified in a package's controller. It is possible to access a different
+translation package using the *i18n* function from models and view, which is
+necessary when strings from the site configuration are used, or packages do not
+have their own controller (which is the case for config mode wizard components).
+
+.. code-block:: lua
+
+  local site_i18n = i18n 'gluon-site'
+  local msg = site_i18n._translate('gluon-config-mode:welcome')
+
 Adding translation templates to Gluon packages
 ----------------------------------------------
 
@@ -45,7 +58,7 @@ script in the ``contrib`` directory:
 
 The same command can be run again to update the template.
 
-In addition, some additions to the Makefile must be made. Instead of LEDE's default *package.mk*,
+In addition, the Makefile must be adjusted. Instead of LEDE's default *package.mk*,
 the Gluon version (``../gluon.mk`` for core packages) must be used. The i18n files must be installed
 and PKG_CONFIG_DEPENDS must be added::
 
@@ -92,5 +105,5 @@ Adding support for new languages
 --------------------------------
 
 A list of all languages supported by *gluon-web* can be found in ``package/gluon.mk``.
-New languages just need to be added to *GLUON_SUPPORTED_LANGS*, after a human-readable
+New languages just need to be added to *GLUON_SUPPORTED_LANGS*, and a human-readable
-language name has been defined in the same file.
+language name must be defined.

docs/dev/web/view.rst

@@ -52,4 +52,4 @@ variables and functions should always be available for the embedded Lua code:
     Use ``node(unpack(request))`` to get the node for the current page.
   - *pcdata* (*str*): Escapes HTML entities in the passed string.
   - *urlencode* (*str*): Escapes the passed string for use in an URL.
-  - *translate*, *_translate* and *translatef*: see :doc:`i18n`
+  - *translate*, *_translate*, *translatef* and *i18n*: see :doc:`i18n`