Translations

Translations

noVNC uses a fairly standard gettext based system for translations. There are some extra scripts to handle the HTML files and to convert the translations to a format easily read from Javascript.

Marking

Code

Strings that need to be translated are marked by wrapping them in the function _(). E.g.:

document.getElementById('textElement').innerHTML = _("Some text");

Remember to only mark literals, not variables or expressions.

Then function _() is an alias for Util.Localisation.get(). New modules need to set up this alias by doing:

var _ = Util.Localisation.get;

Just remember to avoid putting this in the global scope.

HTML

Every visible string in the HTML files is translated by default. The attribute translate can be set to no to prevent translations. This attribute is inherited so if you wish to translate just a single child element then you need to specify translate="yes" on that child.

Updating

At some point it is time to update the translations based on all the additions and changes made to the code and HTML. This is usually done close to the release, after a "string freeze".

This work requires some extra Javascript modules. Install this by running npm install in the root noVNC directory. The gettext suite of tools also needs to be installed.

The first step is scanning the project and updating the template:

make -C po update-pot

This will re-generate the file po/noVNC.pot. Check in this file after you've reviewed it.

Next the individual translation files will be updated by running the command:

make -C po update-po

This will merge all .po files with the new changes in noVNC.pot. Do not check in these files at this point. Instead send out these files to the translators and reset the files back to how they were. This avoids needless commits cluttering up the history.

The translators can use standard gettext tools and procedures for updating the files. Commit the files once they are fully translated.

The code cannot use the .po files as they are, so they need to be converted to a Javascript representation:

make -C po update-js

Commit the files that have updated translations so that people downloading the project do not have to install all these extra tools.

Adding new languages

A new language is added by doing:

cd po
msginit --locale=fr_FR.UTF-8

Make sure that .UTF-8 is included in the locale string to avoid issues with character encodings.

Next, edit po/Makefile and app/ui.js to update the LINGUAS variables. Try to keep these lists alphabetically ordered. Note that the locale name has been normalised by msginit so pay attention to what it actually generated.

Finally fill in the new .po the same way as an existing translation would be handled.