i18n.rst 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596
  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 must be fully translatable. English texts are required.
  7. * German translations are recommended. Other supported languages, especially French, are
  8. nice-to-have, but not required. If you don't know a language well, rather leave the translation
  9. blank, so it is obvious that there is no proper translation yet.
  10. * Existing expert mode packages should be made translatable as soon as possible.
  11. * The "message IDs" (which are the arguments to the *translate* function) should be the
  12. English texts.
  13. i18n support in Gluon
  14. ---------------------
  15. Internationalization support is available in all components (models, view and
  16. controllers) of *gluon-web*-based packages. Strings are translated using the *translate*,
  17. *_translate* and *translatef* functions (*translate* for static strings, *translatef*
  18. for printf-like formatted string; *_translate* works the same as *translate*, but
  19. will return *nil* instead of the original string when no translation is available)
  20. . In views, the special tags ``<%:...%>`` can be used to translate the contained string.
  21. Example from the *gluon-config-mode-geo-location* package:
  22. .. code-block:: lua
  23. local share_location = s:option(Flag, "location", translate("Show node on the map"))
  24. Adding translation templates to Gluon packages
  25. ----------------------------------------------
  26. The i18n support is based on the standard gettext system. For each translatable package,
  27. a translation template with extension ``.pot`` can be created using the *i18n-scan.pl*
  28. script in the ``contrib`` directory:
  29. .. code-block:: sh
  30. cd package/gluon-web-mesh-vpn-fastd
  31. mkdir i18n
  32. cd i18n
  33. ../../../contrib/i18n-scan.pl ../files ../luasrc > gluon-web-mesh-vpn-fastd.pot
  34. The same command can be run again to update the template.
  35. In addition, some additions to the Makefile must be made. Instead of LEDE's default *package.mk*,
  36. the Gluon version (``../gluon.mk`` for core packages) must be used. The i18n files must be installed
  37. and PKG_CONFIG_DEPENDS must be added::
  38. ...
  39. include ../gluon.mk
  40. PKG_CONFIG_DEPENDS += $(GLUON_I18N_CONFIG)
  41. ...
  42. define Build/Compile
  43. $(call GluonBuildI18N,gluon-web-mesh-vpn-fastd,i18n)
  44. endef
  45. define Package/gluon-web-mesh-vpn-fastd/install
  46. ...
  47. $(call GluonInstallI18N,gluon-web-mesh-vpn-fastd,$(1))
  48. endef
  49. ...
  50. Adding translations
  51. -------------------
  52. A new translation file for a template can be added using the *msginit* command:
  53. .. code-block:: sh
  54. cd package/gluon-web-mesh-vpn-fastd/i18n
  55. msginit -l de
  56. This will create the file *de.po* in which the translations can be added.
  57. The translation file can be updated to a new template version using the *msgmerge* command:
  58. .. code-block:: sh
  59. msgmerge -U de.po gluon-web-mesh-vpn-fastd.pot
  60. After the merge, the translation file should be checked for "fuzzy matched" entries where
  61. the original English texts have changed. All entries from the translation file should be
  62. translated in the *.po* file (or removed from it, so the original English texts are displayed
  63. instead).
  64. Adding support for new languages
  65. --------------------------------
  66. A list of all languages supported by *gluon-web* can be found in ``package/gluon.mk``.
  67. New languages just need to be added to *GLUON_SUPPORTED_LANGS*, after a human-readable
  68. language name has been defined in the same file.