novelWriter/i18n/README.md

novelWriter Internationalisation

The i18n folder contains the translation files for the Qt5 GUI. There are two types of files involved: the nw_XX.ts and the nw_XX.qm files. The nw_XX.ts files are located in the i18n folder at the root of the repository, and the nw_XX.qm together with the project_XX.json files are located in novelwriter/assets/i18n. The latter are JSON translation maps for the novelWriter projects, used by the Build Novel Project tool.

Note

When making a new translation, or updating an existing one, only commit the nw_XX.ts you have made changes to. The qtlupdate command mentioned below will likely modify all nw_XX.ts slightly, but please don't commit those changes to the pull request.

Qt GUI Localisation

The .qm files are the actual files used by the application to translate the GUI into another language other than the default British English. The files are not generated by default. They can be built with:

python3 setup.py qtlrelease

To add a new translation file, first add a new entry in the novelWriter.pro file under the TRANSLATIONS variable. Please use the underscore syntax for file names as the importer expects this format.

After adding the entry in the .pro file, run:

python3 setup.py qtlupdate

This will build a new i18n/nw_XX.ts file for the language you just added. The file can then be edited with the Qt 5 Linguist application provided by Qt. This is by far easier than manually editing the .ts file. Please select "English" and "United Kingdom" as the source langauge when prompted by Qt 5 Linguist.

When you're done editing, you can build the novelwriter/assets/i18n/nw_XX.qm file and test it in novelWriter. The Preferences dialog should list the newly added language, and you can select it and test it.

Please do not submit the .qm files to the repository. Only the .ts file you just added in the i18n folder is needed.

Note

These commands require that you have the tools Qt 5 Linguist and the PyQt5 tool pylupdate5 installed on your system.

For Ubuntu/Debian, run:

sudo apt install qttools5-dev-tools pyqt5-dev-tools

Missing QtBase Translations

The default Qt dialogs also have translations, for instance for standard buttons like "Yes", "No", "Ok", "Cancel", etc. Generally, these translations files are installed with the Qt libraries on your system, and novelWriter will collect those translations from there. However, these translations are missing for many languages.

As a starting point, there is no need to translate any entries in the .ts files that are under elements starting with the letter "Q", like "QPlatformTheme", "QWizard", etc. If these turn up in English in novelWriter after activating a translation, it means they are probably missing in the Qt library, and you may also need to translate these.

These additional translation entries are generated from a file named i18n/qtbase.py, which is not a file that novelWriter uses. It is there only to generate these additional entries for the .ts files.

Project Localisation

Projects can have a different language setting than the GUI itself. The files with format project_XX.json in novelwriter/assets/i18n are simple translation maps for text that goes into the exported documents generated by the Build Novel Project tool.

The files are loaded based on the language setting in the build tool. At the present time, no other parts of the application use these files. Since these are used as replacement lookups, they are maintained as plain JSON files. The main usage is to generate chapter headers as number words.

Adding new translations for these files is easy. Just copy the project_en.json file, rename it to the appropriate language coded filename, and edit it. Please use the underscore as separator if a language needs to be localised to a specific country under a language. The importer will for instance look for en_US first, then use en if it is not found. If there are no matching files, the project falls back to using English.