i18n.rst 3.4 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788
  1. Internationalization support
  2. ============================
  3. General guidelines
  4. ------------------
  5. * All config mode packages must be fully translatable, with complete English and German texts.
  6. * All new expert mode packages be fully translatable. English texts are required, German texts recommended.
  7. * Existing expert mode packages should be made translatable as soon as possible.
  8. * The "message IDs" (which are the arguments to the ``translate`` function) should be the
  9. English texts.
  10. i18n support in LuCI
  11. --------------------
  12. Internationalization support can be found in the ``luci.i18n`` package.
  13. Strings are translated using the ``i18n.translate`` and ``i18n.translatef`` functions
  14. (``translate`` for static strings, ``translatef`` for printf-like formatted string).
  15. Example from the ``gluon-config-mode-geo-location`` package::
  16. local i18n = require "luci.i18n"
  17. o = s:option(cbi.Flag, "_location", i18n.translate("Show node on the map"))
  18. Adding translation templates to Gluon packages
  19. ----------------------------------------------
  20. The i18n support is based on the standard gettext system. For each translatable package,
  21. a translation template with extension ``.pot`` can be created using the ``i18n-scan.pl``
  22. script from the LuCI repository::
  23. cd package/gluon-config-mode-geo-location
  24. mkdir i18n
  25. cd i18n
  26. ../../../packages/luci/build/i18n-scan.pl ../files > gluon-config-mode-geo-location.pot
  27. The entries in the template can be reordered after the generation if desirable. Lots of standard
  28. translations like "Cancel" are already available in the LuCI base translation file (see
  29. ``packages/luci/po/templates/base.pot``) and can be removed from the template.
  30. In addition, some additions to the Makefile must be made. Instead of OpenWrt's default package.mk,
  31. the Gluon version ``$(GLUONDIR)/include/package.mk`` must be used. The i18n files must be installed
  32. and PKG_CONFIG_DEPENDS must be added::
  33. ...
  34. include $(GLUONDIR)/include/package.mk
  35. PKG_CONFIG_DEPENDS += $(GLUON_I18N_CONFIG)
  36. ...
  37. define Build/Compile
  38. $(call GluonBuildI18N,gluon-config-mode-geo-location,i18n)
  39. endef
  40. define Package/gluon-config-mode-geo-location/install
  41. ...
  42. $(call GluonInstallI18N,gluon-config-mode-geo-location,$(1))
  43. endef
  44. ...
  45. Adding translations
  46. -------------------
  47. A new translation file for a template can be added using the ``msginit`` command::
  48. cd package/gluon-config-mode-geo-location/i18n
  49. msginit -l de
  50. This will create the file ``de.po`` in which the translations can be added.
  51. The translation file can be updated to a new template version using the ``msgmerge`` command::
  52. msgmerge -U de.po gluon-config-mode-geo-location.pot
  53. After the merge, the translation file should be checked for "fuzzy matched" entries where
  54. the original English texts have changed. All entries from the the translation file should be
  55. translated in the ``.po`` file (or removed from it, so the original English texts are displayed
  56. instead).
  57. Adding support for new languages
  58. --------------------------------
  59. A list of all languages supported by LuCI can be found in the ``include/package.mk`` file of
  60. the Gluon repository. Adding translations for these languages is straightforward using the ``msginit``
  61. command.
  62. For other languages, support must be added tu LuCI first, which constitutes completely translating
  63. the ``base.pot``. Please contact the upstream LuCI maintainers if you'd like to do this.