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 -----------------