diff options
Diffstat (limited to 'docs/i18n.md')
| -rw-r--r-- | docs/i18n.md | 116 |
1 files changed, 100 insertions, 16 deletions
diff --git a/docs/i18n.md b/docs/i18n.md index 226a406c2a..442ec2d0dd 100644 --- a/docs/i18n.md +++ b/docs/i18n.md @@ -1,19 +1,103 @@ -# General -Translations are saved in the folder po/ for each module and application. You find the reference in po/templates/<package>.pot. The actual translation files can be found at po/[lang]/[package].po . +# Internationalization (i18n) -In order to use the commands below you need to have the _gettext'' utilities (''msgcat'', ''msgfmt'', ''msgmerge_) installed on your system. +See [online wiki](https://github.com/openwrt/luci/wiki/i18n) for latest version. -# Rebuild po files +## Use translation function + +### Translations in JavaScript + +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. + +If you have multi line strings you can split them with concatenation: +```js +var mystr = _('this string will translate ' + + 'correctly even though it is ' + + 'a multi line string!'); +``` + +You may also use line continuations `\` syntax: + +```js +var mystr = _('this string will translate \ + correctly even though it is \ + a multi line string'); +``` + +Usually if you have multiple sentences you may need to use a line break then use the `<br />` HTML tag: +```js +var mystr = _('Port number.<br />' + + 'E.g. 80 for HTTP'); +``` + +To simplify a job for translators it may be better to split into separate keys without the `<br />`: +```js +var mystr = _('Port number.') + '<br />' + + _('E.g. 80 for HTTP'); +``` +Please use `<br />` and **not** `<br>` or `<br/>`. + +If you have a link inside a translation then try to move its attributes out of a translation key like: +```js +var mystr = _('For further information <a %s>check the wiki</a>') + .format('href="https://openwrt.org/docs/" target="_blank" rel="noreferrer"') +``` +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"`). + +### Translations in LuCI lua+html templates +Use the `<%: text to translate %>` as documented on [Templates](./Templates.md) + +### Translations in Lua controller code and Lua CBIs +As hinted at in the Templates doc, the `%:` is actually invoking a `translate()` function. +In most controller contexts, this is already available for you, but if necessary, is available for include in `luci.i18n.translate` + + +## Translation files +Translations are saved in the folder `po/` within each individual LuCI component directory, e.g. `applications/luci-app-acl/po/`. +You find the reference in `po/templates/<package>.pot`. +The actual translation files can be found at `po/[lang]/[package].po`. + +In order to use the commands below you need to have the `gettext` utilities (`msgcat`, `msgfmt`, `msgmerge`) installed on your system. +On Debian/Ubuntu you can install with `sudo apt install gettext`. + +### Rebuild po files If you want to rebuild the translations after you made changes to a package this is an easy way: - - ./build/i18n-scan.pl applications/[application] > applications/[application]/po/templates/[application_basename].pot - ./build/i18n-update.pl applications/[application]/po - - Example: - ./build/i18n-scan.pl applications/luci-app-firewall > applications/luci-app-firewall/po/templates/firewall.pot - ./build/i18n-update.pl applications/luci-app-firewall/po - (note that the directory argument can be omitted for i18n-update.pl to update all apps) - -*Note:* Some packages share translation files, in this case you need to scan through all their folders. The first command from above should then be: - - ./build/i18n-scan.pl applications/[package-1] applications/[package-2] applications/[package-n] > [location of shared template]/[application].pot + + ./build/i18n-scan.pl applications/[application] > applications/[application]/po/templates/[application_basename].pot + ./build/i18n-update.pl applications/[application]/po + +Example: + + ./build/i18n-scan.pl applications/luci-app-acl > applications/luci-app-acl/po/templates/acl.pot + ./build/i18n-update.pl applications/luci-app-acl/po + +Note that the directory argument can be omitted for `i18n-update.pl` to update all apps. + +Some packages share translation files, in this case you need to scan through all their folders. +The first command from above should then be: + + ./build/i18n-scan.pl applications/[package-1] applications/[package-2] applications/[package-n] > [location of shared template]/[application].pot + +*Note:* The translation catalog for the base system covers multiple components, use the following commands to update it: + + ./build/mkbasepot.sh + ./build/i18n-update.pl + +### LMO files +The `*.po` files are big so Luci needs them in a compact compiled [LMO format](./LMO.md). +Luci reads `*.lmo` translations from `/usr/lib/lua/luci/i18n/` folder. +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. + +In order to quickly convert a single `.po` file to `.lmo` file for testing on the target system use the `po2lmo` utility. +You will need to compile it from the `luci-base` module: + + $ cd modules/luci-base/src/ + $ make po2lmo + $ ./po2lmo + Usage: ./po2lmo input.po output.lmo + +Now you can compile and upload translation: + + ./po2lmo ../../../applications/luci-app-acl/po/ar/acl.po ./acl.ar.lmo + scp ./acl.ar.lmo root@192.168.1.1:/usr/lib/lua/luci/i18n/ + +You can change language in [System /Language and Style](http://192.168.1.1/cgi-bin/luci/admin/system/system) and check the translation.
\ No newline at end of file |