i18n.md

   1 # Internationalization (i18n)
   2
   3 See [online wiki](https://github.com/openwrt/luci/wiki/i18n) for latest version.
   4
   5 ## Use translation function
   6
   7 ### Translations in JavaScript
   8
   9 Wrap translatable strings with `_()` e.g.  `_('string to translate')` and the `i18n-scan.pl` and friends will correctly identify these strings as they do with all the existing translations.
  10
  11 If you have multi line strings you can split them with concatenation:
  12 ```js
  13 var mystr = _('this string will translate ' +
  14         'correctly even though it is ' +
  15         'a multi line string!');
  16 ```
  17
  18 You may also use line continuations `\` syntax:
  19
  20 ```js
  21 var mystr = _('this string will translate \
  22         correctly even though it is \
  23         a multi line string');
  24 ```
  25
  26 Usually if you have multiple sentences you may need to use a line break then use the `<br />` HTML tag:
  27 ```js
  28 var mystr = _('Port number.<br />' +
  29         'E.g. 80 for HTTP');
  30 ```
  31
  32 To simplify a job for translators it may be better to split into separate keys without the `<br />`:
  33 ```js
  34 var mystr = _('Port number.') + '<br />' +
  35         _('E.g. 80 for HTTP');
  36 ```
  37 Please use `<br />` and **not** `<br>` or `<br/>`.
  38
  39 If you have a link inside a translation then try to move its attributes out of a translation key like:
  40 ```js
  41 var mystr = _('For further information <a %s>check the wiki</a>')
  42         .format('href="https://openwrt.org/docs/" target="_blank" rel="noreferrer"')
  43 ```
  44 This will generate a full link with HTML `For further information <a href="https://openwrt.org/docs/" target="_blank" rel="noreferrer">check the wiki</a>`. The `noreferrer` is important when making a link that is opened in a new tab (`target="_blank"`).
  45
  46 ### Translations in LuCI lua+html templates
  47 Use the `<%: text to translate %>` as documented on [Templates](./Templates.md)
  48
  49 ### Translations in Lua controller code and Lua CBIs
  50 As hinted at in the Templates doc, the `%:` is actually invoking a `translate()` function.
  51 In most controller contexts, this is already available for you, but if necessary, is available for include in `luci.i18n.translate`
  52
  53
  54 ## Translation files
  55 Translations are saved in the folder `po/` within each individual LuCI component directory, e.g. `applications/luci-app-acl/po/`.
  56 You find the reference in `po/templates/<package>.pot`.
  57 The actual translation files can be found at `po/[lang]/[package].po`.
  58
  59 In order to use the commands below you need to have the `gettext` utilities (`msgcat`, `msgfmt`, `msgmerge`) installed on your system.
  60 On Debian/Ubuntu you can install with `sudo apt install gettext`.
  61
  62 ### Initialize po files
  63
  64 When you add or update an app, simply run from your app folder:
  65
  66     ../../build/i18n-add-language.sh
  67
  68 This creates the skeleton po files for all existing languages open for translation for your app.
  69
  70 Or from the luci repo root:
  71
  72     ./build/i18n-add-language.sh
  73
  74 This creates the skeleton po files for all existing languages open for translation for all sub-folders.
  75
  76 ### Rebuild po files
  77 If you want to rebuild the translations after you made changes to a package this is an easy way:
  78
  79     ./build/i18n-scan.pl applications/[application] > applications/[application]/po/templates/[application_basename].pot
  80     ./build/i18n-update.pl applications/[application]/po
  81
  82 Example:
  83
  84     ./build/i18n-scan.pl applications/luci-app-acl > applications/luci-app-acl/po/templates/acl.pot
  85     ./build/i18n-update.pl applications/luci-app-acl/po
  86
  87 Note that the directory argument can be omitted for `i18n-update.pl` to update all apps.
  88
  89 Some packages share translation files, in this case you need to scan through all their folders.
  90 The first command from above should then be:
  91
  92     ./build/i18n-scan.pl applications/[package-1] applications/[package-2] applications/[package-n] > [location of shared template]/[application].pot
  93
  94 *Note:* The translation catalog for the base system covers multiple components, use the following commands to update it:
  95
  96     ./build/mkbasepot.sh
  97     ./build/i18n-update.pl
  98
  99 ### LMO files
 100 The `*.po` files are big so Luci needs them in a compact compiled [LMO format](./LMO.md).
 101 Luci reads `*.lmo` translations from `/usr/lib/lua/luci/i18n/` folder.
 102 E.g. `luci-app-acl` has an Arabic translation in `luci-i18n-acl-ar` package that installs `/usr/lib/lua/luci/i18n/acl.ar.lmo` file.
 103
 104 In order to quickly convert a single `.po` file to `.lmo` file for testing on the target system use the `po2lmo` utility.
 105 You will need to compile it from the `luci-base` module:
 106
 107      $ cd modules/luci-base/src/
 108      $ make po2lmo
 109      $ ./po2lmo
 110      Usage: ./po2lmo input.po output.lmo
 111
 112 Now you can compile and upload translation:
 113
 114      ./po2lmo ../../../applications/luci-app-acl/po/ar/acl.po ./acl.ar.lmo
 115      scp ./acl.ar.lmo root@192.168.1.1:/usr/lib/lua/luci/i18n/
 116
 117 You can change language in [System /Language and Style](http://192.168.1.1/cgi-bin/luci/admin/system/system) and check the translation.