From b4068fa7f001bc4cd48a4517e1206a2fdf8f6606 Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Sat, 25 Apr 2015 19:22:15 +0200
Subject: [PATCH] docs: add i18n howto

---
 docs/conf.py      |  2 +-
 docs/dev/i18n.rst | 80 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst    |  1 +
 3 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 docs/dev/i18n.rst

diff --git a/docs/conf.py b/docs/conf.py
index 4cf0a96e..0856ed6f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -47,7 +47,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'Gluon'
-copyright = '2014, Project Gluon'
+copyright = '2015, Project Gluon'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/docs/dev/i18n.rst b/docs/dev/i18n.rst
new file mode 100644
index 00000000..26b36436
--- /dev/null
+++ b/docs/dev/i18n.rst
@@ -0,0 +1,80 @@
+Internationalization support
+============================
+
+General guidelines
+------------------
+
+* All config mode packages must be fully translatable, with complete English and German texts.
+* All new expert mode packages be fully translatable. English texts are required, German texts recommended.
+* 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 LuCI
+--------------------
+
+Internationalization support can be found in the ``luci.i18n`` package.
+Strings are translated using the ``i18n.translate`` and ``i18n.translatef`` functions
+(``translate`` for static strings, ``translatef`` for printf-like formatted string).
+
+Example from the ``gluon-config-mode-geo-location`` package::
+
+  local i18n = require "luci.i18n"
+  o = s:option(cbi.Flag, "_location", i18n.translate("Show node on the map"))
+
+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 from the LuCI repository::
+
+  cd package/gluon-config-mode-geo-location
+  mkdir i18n
+  cd i18n
+  ../../../packages/luci/build/i18n-scan.pl ../files > gluon-config-mode-geo-location.pot
+
+The entries in the template can be reordered after the generation if desirable. Lots of standard
+translations like "Cancel" are already available in the LuCI base translation file (see
+``packages/luci/po/templates/base.pot``) and can be removed from the template.
+
+In addition, the i18n files must be installed in the package's Makefile::
+
+  define Build/Compile
+    $(call GluonBuildI18N,gluon-config-mode-geo-location,i18n)
+  endef
+
+  define Package/gluon-config-mode-geo-location/install
+    ...
+    $(call GluonInstallI18N,gluon-config-mode-geo-location,$(1))
+  endef
+
+
+Adding translations
+-------------------
+
+A new translation file for a template can be added using the ``msginit`` command::
+
+  cd package/gluon-config-mode-geo-location/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::
+
+  msgmerge -U de.po gluon-config-mode-geo-location.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 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 LuCI can be found in the ``include/package.mk`` file of
+the Gluon repository. Adding translations for these languages is straightforward using the ``msginit``
+command.
+
+For other languages, support must be added tu LuCI first, which constitutes completely translating
+the ``base.pot``. Please contact the upstream LuCI maintainers if you'd like to do this.
diff --git a/docs/index.rst b/docs/index.rst
index a53c0a8d..57ffd1dd 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -40,6 +40,7 @@ Developer Documentation
    dev/upgrade
    dev/configmode
    dev/wan
+   dev/i18n
 
 Supported Devices
 -----------------