# 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 `nw/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:
```bash
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:
```bash
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 `nw/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:
```bash
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 `nw/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.