docs/dev/web/i18n.rst

+Internationalization support
+============================
+
+General guidelines
+------------------
+
+* All config mode packages must be fully translatable, with complete English and German texts.
+* All new expert mode packages must be fully translatable. English texts are required.
+* German translations are recommended. Other supported languages, especially French, are
+  nice-to-have, but not required. If you don't know a language well, rather leave the translation
+  blank, so it is obvious that there is no proper translation yet.
+* Existing expert mode packages should be made translatable as soon as possible.
+* The "message IDs" (which are the arguments to the *translate* function) should be the
+  English texts.
+
+i18n support in Gluon
+---------------------
+
+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).
+
+In views, the special tags ``<%:...%>`` can be used to translate the contained string.
+
+Example from the *gluon-config-mode-geo-location* package:
+
+.. code-block:: lua
+
+  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
+----------------------------------------------
+
+The i18n support is based on the standard gettext system. For each translatable package,
+a translation template with extension ``.pot`` can be created using the *i18n-scan.pl*
+script in the ``contrib`` directory:
+
+.. code-block:: sh
+
+  cd package/gluon-web-mesh-vpn-fastd
+  mkdir i18n
+  cd i18n
+  ../../../contrib/i18n-scan.pl ../files ../luasrc > gluon-web-mesh-vpn-fastd.pot
+
+The same command can be run again to update the template.
+
+In addition, the Makefile must be adjusted. Instead of OpenWrt'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::
+
+  ...
+  include ../gluon.mk
+
+  PKG_CONFIG_DEPENDS += $(GLUON_I18N_CONFIG)
+  ...
+  define Build/Compile
+    $(call GluonBuildI18N,gluon-web-mesh-vpn-fastd,i18n)
+  endef
+
+  define Package/gluon-web-mesh-vpn-fastd/install
+    ...
+    $(call GluonInstallI18N,gluon-web-mesh-vpn-fastd,$(1))
+  endef
+  ...
+
+
+Adding translations
+-------------------
+
+A new translation file for a template can be added using the *msginit* command:
+
+.. code-block:: sh
+
+  cd package/gluon-web-mesh-vpn-fastd/i18n
+  msginit -l de
+
+This will create the file *de.po* in which the translations can be added.
+
+The translation file can be updated to a new template version using the *msgmerge* command:
+
+.. code-block:: sh
+
+  msgmerge -U de.po gluon-web-mesh-vpn-fastd.pot
+
+After the merge, the translation file should be checked for "fuzzy matched" entries where
+the original English texts have changed. All entries from the translation file should be
+translated in the *.po* file (or removed from it, so the original English texts are displayed
+instead).
+
+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*, and a human-readable
+language name must be defined.

docs/dev/web/view.rst

+Views
+=====
+
+The template parser reads views from the ``view`` subdirectory of a
+gluon-web application (``/lib/gluon/config-mode/view`` for the config mode,
+``lib/gluon/status-page/view`` for the status page).
+Writing own views should usually be avoided in favour of using :doc:`model`
+with their predefined views.
+
+Views are partial HTML pages, with additional template tags that allow
+to embed Lua code and translation strings. The following tags are defined:
+
+  - ``<%`` ... ``%>`` evaluates the enclosed Lua expression.
+  - ``<%|`` ... ``%>`` evaluates the enclosed Lua expression and prints its value.
+  - ``<%=`` ... ``%>`` evaluates the enclosed Lua expression and prints its value
+    *without escaping HTML entities*. This is useful when the value contains HTML code.
+  - ``<%+`` ... ``%>`` includes another template.
+  - ``<%:`` ... ``%>`` translates the enclosed string using the loaded i18n catalog.
+  - ``<%_`` ... ``%>`` translates the enclosed string *without escaping HTML entities*
+    in the translation. This only makes sense when the i18n catalog contains HTML code.
+  - ``<%#`` ... ``%>`` is a comment.
+
+All of these also come in the whitespace-stripping variants ``<%-`` and ``-%>`` that
+remove all whitespace before or after the tag.
+
+Complex combinations of HTML and Lua code are possible, for example:
+
+.. code-block:: text
+
+  <div>
+    <% if foo then %>
+      Content
+    <% end %>
+  </div>
+
+
+Variables and functions
+-----------------------
+
+Many call sites define additional variables (for example, model templates can
+access the model as *self* and a unique element ID as *id*), but the following
+variables and functions should always be available for the embedded Lua code:
+
+  - *renderer*: :ref:`web-controller-template-renderer`
+  - *http*: :ref:`web-controller-http`
+  - *request*: Table containing the path components of the current page
+  - *url* (*path*): returns the URL for the given path, which is passed as a table of path components.
+  - *attr* (*key*, *value*): Returns a string of the form ``key="value"``
+    (with a leading space character before the key).
+
+    *value* is converted to a string (tables are serialized as JSON) and HTML entities
+    are escaped. Returns an empty string when *value* is *nil* or *false*.
+  - *include* (*template*): Includes another template.
+  - *node* (*path*, ...): Returns the controller node for the given page (passed as
+    one argument per path component).
+
+    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*, *translatef* and *i18n*: see :doc:`i18n`