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

In order to use the commands below you need to have the _gettext'' utilities (''msgcat'', ''msgfmt'', ''msgmerge_) installed on your system.

## 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`.

### Initialize po files

When you add or update an app, simply run from your app folder:

    ../../build/i18n-add-language.sh

This creates the skeleton po files for all existing languages open for translation for your app.

Or from the luci repo root:

    ./build/i18n-add-language.sh

This creates the skeleton po files for all existing languages open for translation for all sub-folders.

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