novelWriter/i18n

novelWriter Internationalisation (i18n)

Here you will find instructions for translating novelWriter to a new language or updating the translations for an already existing supported language.

There are two areas relevant to localisation:

• The Qt5 GUI translation files, which consists of nw_XX.ts files. This is the bulk of the translation work.
• The project_XX.json files. See Project Localisation below.

Important:

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

Qt5 GUI Localisation

You will need 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

Workflow

Here's an overview of the localisation workflow:

1. First, create a new branch off of main, and there, generate a new nw_XX.ts translation file.
2. Load the translation file in Qt Linguist. Translate and save your changes.
3. Generate the nw_XX.qm file.
4. Run the application and verify your changes. Iterate from step 2.
5. Once finished, commit your changes and submit your pull request.

When you want to translate new changes, again create a new branch off of main and re-generate the translation file. Continue from step 2.

Generate an Updated Translation File

The i18n folder at the root of the repository contains the nw_XX.ts translation files.

Whether to add a new language to the translation framework, or to update the file against the current source code, you must first run the qtlupdate command:

python3 setup.py qtlupdate i18n/nw_XX.ts

The file name must be in the correct format. All translation files must be located in the i18n folder, start with nw_ and end with .ts. In between goes the language code. It must be a valid ISO language code, otherwise novelWriter will not accept the file.

For instance, the French translation uses the language code fr, so its translation file will be nw_fr.ts

Note: If you run the qtlupdate command without a file name, it will update translation files for all languages.

Edit the Translation File in Qt Linguist

The i18n/nw_XX.ts file can be edited with the Qt Linguist application provided by Qt 5. This is by far easier than manually editing the .ts file.

Please select "English" and "United Kingdom" as the source language if prompted by Qt Linguist.

Verify Your Translation

The application does not use .ts files directly. The novelwriter/assets/i18n/nw_XX.qm files are the actual files used to translate the GUI into another language other than the default British English. These files are not generated by default, but they can be built with:

python3 setup.py qtlrelease

You can now test the translation in novelWriter. The Preferences dialog should list the newly added language, so go ahead and select it.

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

Missing QtBase Translations

The default Qt dialogs also have translations, for instance for standard buttons like "Yes", "No", "Ok", "Cancel", etc. Generally, these translation 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 Novel Project 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 open it in a text editor. 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.